Push Notification Formats

QuickBlox provides two types of push notifications you can send:

  1. Platform based push notification will be delivered to the specified platform only, for example, iOS or Android only.
  2. Universal push notifications will be delivered to all possible devices/platforms for specified users.

Platform-based push notification

A platform-based push notification will be delivered to a specified platform only, for example, iOS or Android. To specify platform use event.push_type parameter within Create Event request. With platform-based push notification, you can use all specified features of a particular platform. There are no restrictions.

General requirements

A message format is a key=value string where a key is raw text and value is CGI escaped and Base64 encoded. Each pair should be separated by &.

Example:

Plain message: key1=c29tZXZhbHVlMQ==&key2=YW5vdGhlcnZhbHVlMg==&key3=dGhpcmRleGFtcGxl

❗️

Symbol & should be escaped by %26.

iOS

To meet Apple payload requirements review this document.

Example:

  1. Initial JSON payload:
    { "aps" : { "alert" : "You got your emails.", "badge" : 9, "sound" : "bingbong.aiff" }, "acme1" : "bar", "acme2" : 42 }
  2. Base64 Encoded data:
    ew0KICAgICJhcHMiIDogew0KICAgICAgICAiYWxlcnQiIDogIllvdSBnb3QgeW91ciBlbWFpbHMuIiwNCiAgICAgICAgImJhZ GdlIiA6IDksDQogICAgICAgICJzb3VuZCIgOiAiYmluZ2JvbmcuYWlmZiINCiAgICB9LA0KICAgICJhY21lMSIgOiAiYmFyIiwNCiAg ICAiYWNtZTIiIDogNDINCn0=
  3. Final message (for iOS pushes you should add payload= before message):
    event.message=payload=ew0KICAgICJhcHMiIDogew0KICAgICAgICAiYWxlcnQiIDogIllvdSBnb3QgeW91ciBlbWFpbHMuIiwNCiAgICAgICAg ImJhZGdlIiA6IDksDQogICAgICAgICJzb3VuZCIgOiAiYmluZ2JvbmcuYWlmZiINCiAgICB9LA0KICAgICJhY21lMSIgOiAiYmFyIiwNCi AgICAiYWNtZTIiIDogNDINCn0=

Android

To meet FCM requirements review this document. The overall principles are as follows:

  1. data.message key is required and should be first.
  2. Values should be CGI escaped before Base64 encoding.
  3. The required field collapse_key is added automatically before sending and contains value event<ID>.
  4. Message format is a data.key1=value1&...&data.keyN=valueN.

Example:

  1. Initial plain message:
    data.message=I love M&M's! Especially red one!
  2. CGI-escaped:
    data.message=I+love+M%26M%27s%21+Especially+red+one%21
  3. Base64-encoded:
    data.message=SStsb3ZlK00lMjZNJTI3cyUyMStFc3BlY2lhbGx5K3JlZCtvbmUlMjE=
  4. Final message:
    event.message=data.message=SStsb3ZlK00lMjZNJTI3cyUyMStFc3BlY2lhbGx5K3JlZCtvbmUlMjE=

Universal Push Notifications

Universal push notifications will be delivered to all possible devices/platforms for specified users. To send Universal push notifications just omit event.push_type parameter within a Create Event request.

Send a simple text

If you would like to send just a text push message (without any parameters) use the format below.

Example:

  1. Initial plain message:
    I love M&M's! Especially red one!
  2. Base64-encoded:
    SSBsb3ZlIE0mTSdzISBFc3BlY2lhbGx5IHJlZCBvbmUh
  3. Final message:
    event.message=SSBsb3ZlIE0mTSdzISBFc3BlY2lhbGx5IHJlZCBvbmUh

Use custom parameters

🚧

Custom parameters are available for iOS and Android platforms only.

With custom parameters, you can achieve a behavior similar to platform-based push notifications.

There are some standard parameters, which will be translated to particular platform parameters:

  • message push text will be translated to aps.alert.body for iOS and to data.message for Android.
  • ios_badge will be translated to aps.badge for iOS. Ignored for Android.
  • ios_sound will be translated to aps.sound for iOS. Ignored for Android.
  • ios_content_available=1 will be translated to aps.content-available for iOS. Ignored for Android.
  • ios_mutable_content=1 will be translated to aps.mutable-content for iOS. Ignored for Android.
  • ios_category will be translated to aps.category for iOS. Ignored for Android.
  • ios_voip=1 will initiate VoIP push notification for iOS if user has VoIP push subscription. Otherwise, iOS user will receive standart iOS push. For Android, it will be a standard push.

You can use any other custom parameters. They will be added as well according to the specific platform push format. For iOS, it will be root keys, for Android - data.X.

Example:

  1. Initial JSON message:
    {"message": "Message received from Bob", "ios_badge": 5, "ios_sound": "mysound.wav", "user_id": "234"}
  2. Base64-encoded:
    c29tZXZhbHVlMQc29tZXZhbHVlMQc29tZXZhbHVlMQc29tZXZhbHVlMQc29tZXZhbHVlMQ
  3. Final message: event.message=c29tZXZhbHVlMQc29tZXZhbHVlMQc29tZXZhbHVlMQc29tZXZhbHVlMQc29tZXZhbHVlMQ

Client's application will receive next payload:

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo
{
    NSLog(@"New push: %@", userInfo);
}
 
...
 
{
    aps =     {
        alert = "Message received from Bob";
        badge = 5;
        sound = "mysound.wav";
    };
    "user_id" = 234;
}
@Override
protected void onMessage(Context context, Intent intent) {
    String message = "";
 
    for(String key : intent.getExtras().keySet()){
         Log.d(LOG_TAG, key + ": " + intent.getExtras().getString(key));
    }
}
 
...
 
07-21 11:07:26.489  14443-14842/? D/GCMIntentService﹕ message: Message+received+from+Bob
07-21 11:07:26.489  14443-14842/? D/GCMIntentService﹕ user_id: 234
07-21 11:07:26.489  14443-14842/? D/GCMIntentService﹕ collapse_key: event1206083
07-21 11:07:26.489  14443-14842/? D/GCMIntentService﹕ from: 761750217637