Show TOC

Push Notification API ScenariosLocate this document in the navigation structure

Send push notifications to devices that are registered to an application.

Request

URL: http[s]://<host:port>/restnotification/application/<applicationId>

Request Parameters
Parameter Type Description
applicationId Mandatory ID that uniquely identifies an application.
Request Body Example
> POST /restnotification/application/123456789 HTTP/1.1
> Authorization: Basic cHVzaDpzZWNyZXQ=
> User-Agent: curl/7.36.0
> Host: localhost:8080
> Accept: */*
> Content-Type: application/json;charset=utf-8
> Content-Length: 127
> {
 "alert": "alertval",
 "badge": 1,
 "data": "testData",
 "sound": "soundval"
}
< HTTP/1.1 201 Created
< Content-Length: 0
< Date: Mon, 05 May 2014 00:29:38 GMT
< Server: SAP

In this scenario, a status code 201 indicates that the server accepts the push notification request. The server forwards these requests to the external push service such as GCM, BES, BIS, APNS, WNS and so on. The status code does not indicate that the server has successfully delivered the notification to the devices.

Other possible HTTP status codes, you may encounter:

Response

Other possible HTTP status codes, you may encounter:

Code Description
400 Bad Request The request is invalid. Verify the request body.

401 Forbidden

The user who issued the request does not have the required privileges. Ensure that the user is assigned to the Notification User role.

403 Authentication required

No or incorrect credentials provided. Enter the correct credentials.

Users and Devices

To send push notification to all the devices registered to a particular user, use:

URL: http[s]://<host:port>/restnotification/application/<applicationId>/user/<userID>

Request Body Example
> POST /restnotification/application/123456789/user/timmitester HTTP/1.1
> Authorization: Basic cHVzaDpzZWNyZXQ=
> User-Agent: curl/7.36.0
> Host: localhost:8080
> Accept: */*
> Content-Type: application/json;charset=utf-8
> Content-Length: 127
> {
 "alert": "alertval",
 "badge": 1,
 "data": "testData",
 "sound": "soundval"
}
< HTTP/1.1 201 Created
< Set-Cookie: X-SMP-SESSIDSSO=C05E58BE3CFC685ABB945D53C2AF14FD; Path=/; HttpOnly
< Set-Cookie: X-SMP-SESSID=4CC5BC2943E5D3A9B5D924888FC28CB060034F0092911A66B9F079047077798C; Path=/; HttpOnly
< Content-Length: 0
< Date: Mon, 05 May 2014 00:32:35 GMT
< Server: SAP
Registration ID

To send push notification to a device by using an application registration ID, use:

URL: http[s]://<host:port>/restnotification/registration/<applicationRegistrationId>

Request Body Example
> POST /restnotification/registration/9f847e51-3242-4899-9193-39b6e840d657 HTTP/1.1
> Authorization: Basic cHVzaDpzZWNyZXQ=
> User-Agent: curl/7.36.0
> Host: localhost:8080
> Accept: */*
> Content-Type: application/json;charset=utf-8
> Content-Length: 127
> {
 "alert": "alertval",
 "badge": 1,
 "data": "testData",
 "sound": "soundval"
}
< HTTP/1.1 201 Created
< Set-Cookie: X-SMP-SESSIDSSO=D541E4898186AB304F506D13C0C3F1D0; Path=/; HttpOnly
< Set-Cookie: X-SMP-SESSID=FDB39F9BAE8A6E1AD4373765A58E094A14B8FDFB8289CC70E51B77A284C50736; Path=/; HttpOnly
< Content-Length: 0
< Date: Mon, 05 May 2014 00:36:15 GMT
< Server: SAP
Users per application

To send push notification to all the users of an application, use:

URL: http[s]://<host:port>/restnotification/application/<applicationId>/user

Request Body Example
POST /restnotification/application/123456789/user HTTP/1.1
> Authorization: Basic cHVzaDpzZWNyZXQ=
> User-Agent: curl/7.36.0
> Host: localhost:8080
> Accept: */*
> Content-Type: application/json;charset=utf-8
> Content-Length: 277
> {
    "notification": {
        "alert": "alertval",
        "badge": 1,
        "data": "testData",
        "sound": "soundval"
    },
    "users": [
        "timmitester",
        "user1",
        "user2"
    ]
}
< HTTP/1.1 201 Created
< Set-Cookie: X-SMP-SESSIDSSO=9AD06173C8AB9FC05FD6AA8DC55BB9AE; Path=/; HttpOnly
< Set-Cookie: X-SMP-SESSID=DFB2D2AC4EBAA4903553EB7C5A0C90870BD4B8F3A3DC19A5FD984673EB1BD646; Path=/; HttpOnly
< Content-Length: 0
< Date: Mon, 05 May 2014 00:38:32 GMT
< Server: SAP
Registration list

To send push notifications to a list of registrations, use:

URL: http[s]://<host:port>/restnotification/registration/

Request Body Example
POST /restnotification/registration HTTP/1.1
> Authorization: Basic cHVzaDpzZWNyZXQ=
> User-Agent: curl/7.36.0
> Host: localhost:8080
> Accept: */*
> Content-Type: application/json;charset=utf-8
> Content-Length: 466
> {
    "notification": {
        "alert": "alertval",
        "badge": 1,
        "data": "testData",
        "sound": "soundval"
    },
    "registrations": [
        "3078e166-f144-4288-9dbc-1d192afe18d8",
        "9f847e51-3242-4899-9193-39b6e840d657",
        "4d1ccdf9-058a-42cf-a625-c4ed48944729",
        "f05dc905-b859-45fa-afdc-da3b630d2b48",
        "282be579-783e-40fb-b376-25bed5e13606"
    ]
}
< HTTP/1.1 201 Created
< Set-Cookie: X-SMP-SESSIDSSO=BCA5FCB41DD7F451410E3E8BB59E8F7A; Path=/; HttpOnly
< Set-Cookie: X-SMP-SESSID=2AC74022B258178ED3A88E4B2FA10AB41093F53C3D0A77976FE6FE076F1E3CC2; Path=/; HttpOnly
< Content-Length: 0
< Date: Mon, 05 May 2014 00:41:52 GMT
< Server: SAP
Capability

Use capability to identify device capabilities. This enables you to push notifications to applications with specific capabilities rather than to individual applications. To send push notifications to applications that support specific capabilities use:

URL: http[s]://<host:port>/restnotification/capability/<capabilityName>/

Capability supports two modes:
  • Wildcard (*): the device has all capabilities. When a push notification is sent, the device form factor must match.

    For example, Jean registers a device with a wildcard capability capabilityName: * and form factor: tablet, and Jake registers with capabilityName: * and form factor: phone. When the notification capability: 'purchaseOrder-display' and form factor: phone is pushed to both users, only Jake gets the notification. Jean does not get the notification, because the form factor does not match.

  • Match capability name only: the device has a certain capability name. When a push notification is sent, the notification must match the capability, and the form factor is ignored.

    For example, Yijie registers a device with a specific capability name capability: 'purchaseOrder-display' and form factor: phone. When a notification is pushed to capability: 'purchaseOrder-display' and formFactor: tablet, Yijie receives the notification because the capability matches. The form factor formFactor: tablet is ignored.

Request Body Example
POST http://localhost:8082/restnotification/capability/display HTTP/1.1
> Accept: application/json
> Authorization: Basic cHVsaDpzZWNyZXQ=
> 
{
  "notification": {
    "data": "{\"NotificationId\":\"005056AB5B8D1ED4B99CC017A78D2429\",\"Text\": \"You have a new purchase order for approval\",\"NavigationTargetObject\":\"purchaseOrder\",\"NavigationTargetAction\": \"display\",\"NavigationTargetParam\":[{\"Key\": \"ID\",\"Value\":\"4711"}],"Actions\":[{\"ActionId\": \"approve\",\"ActionText\":\"Approve\",\"BulkActionText\":\"Approve all\",\"Nature\":\"POSITIVE\"},{\"ActionId\": \"reject\",\"ActionText\":\"Reject\",\"BulkActionText\":\"Reject all\",\"Nature\":\"NEGATIVE\"}],\"NotificationTypeId\":\"purchaseOrder\"}",
    "alert": "You have a new purchase order for approval",
    "sound": "beep",
    "customParameters": {
      "apns.category": "INVITE_CATEGORY"
    }
  },

  "users": [{
    "badge": 3,
    "formFactor": [
      "tablet",
      "smartphone"
    ],
    "user": "john"
  }, {
    "badge": 2,
    "formFactor": [
      "smartphone"
    ],
    "user": "jane"
  }]
> }
< HTTP/1.1 201 Created
< Content-Type: application/json
Response Body
> {
   "status":    {
      "value": "OK",
      "code": 0
   },
   "results":    [
            {
         "status":          {
            "value": "OK",
            "code": 0
         },

         "registrationId": "00783d2a-7031-49d0-bc3b-1aae90772955"
      },
            {
         "status":          {
            "value": "OK",
            "code": 0
         },
         "registrationId": "3403fdc4-9ecb-48e5-8e11-b2ac99ab0e90"
      }
   ]
}
Customize Push Notification Types
Use customParameters to override the value for a particular notification type. Customize push notification types-alert, badge, data, and sound in the payload by prefixing with:
  • apns
  • bbbis
  • bbbes
  • gcm
  • mpns
  • wns

HTTP Method: POST

Example: Push to all users to the application with application ID "XYZ". Issue a POST method on:
> POST /restnotification/application/XYZ HTTP/1.1
> Authorization: Basic cHVzaDpzZWNyZXQ=
> User-Agent: curl/7.36.0
> Host: localhost:8080
> Accept: */*
> Content-Type: application/json;charset=utf-8
> {
 "alert": "alertval",
 "badge": 1,
 "data": "testData",
 "sound": "soundval"
}
Example: To reset or override the value of the notification type parameter - sound in your Android device, you can use the customParameters to override the value of the sound parameter:
> {
 "alert": "alertval",
 "badge": 1,
 "customParameters": {
   "gcm.sound": "soundforgcm"
 },
 "data": "testData",
 "sound": "soundval"
}
Category (APNS)

Use category for "actionable" APNS push notifications. These notifications can be sent through SAP Mobile Platform and SAP Mobile Platform directly, or through Push Hub.

Example: REST(ful) pushPush request containing a JSON payload. The category is a sub-element of the customParameters element called "apns.category". Issue a POST method on:
> POST /restnotification/registration/<applicationId> HTTP/1.1
> Accept-Encoding: gzip,deflate
> Content-Type: application/json
> Authorization: Basic cHVzaDpzZWNyZXQ=
> Content-Length: 117
> Host: localhost:8080
> Connection: Keep-Alive
> User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
> {
 "alert": "PushAlert",
 "data": "pushTest",
 "customParameters":
 {"apns.category":"SoapUICategory" }
}
Example: non-SAP Gateway notification. Include the header "X-SMP-APNS-CATEGORY". Issue a POST method on:
> POST /Notification/<applicationId> HTTP/1.1
> Accept-Encoding: gzip,deflate
> Content-Type: application/xml
> Authorization: Basic cHVzaDpzZWNyZXQ=
> X-SMP-APNS-CATEGORY: SoapUICategory
> X-SMP-APNS-DATA: pushTest
> Content-Length: 0
> Host: localhost:8080
> Connection: Keep-Alive
> User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
Example: SAP Gateway notification Include the header "X-SAP-POKE-CATEGORY". Issue a POST method on:
> POST /Notification/<applicationId> HTTP/1.1
> Accept-Encoding: gzip,deflate
> Content-Type: application/xml
> Authorization: Basic cHVzaDpzZWNyZXQ=
> X-SAP-POKE-DATA: pushTest
> X-SAP-POKE-CATEGORY: SoapUICategory
> Content-Length: 0
> Host: localhost:8080
> Connection: Keep-Alive
> User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
Example: URL parameter encoded. Append the parameter "category=" to the request URL. Issue a POST method on:
> POST /Notification/<<applicationId>>?alert=PushAlert&data=pushTest&category=SoapUICategory HTTP/1.1
> Accept-Encoding: gzip,deflate
> Content-Type: application/xml
> Authorization: Basic cHVzaDpzZWNyZXQ=
> Content-Length: 0
> Host: localhost:8080
> Connection: Keep-Alive
> User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
Content Available (APNS)

Use contentAvailable for "actionable" APNS push notifications, which enable users to take action without changing focus. These notifications can be sent through SAP Mobile Platform and SAP Mobile Platform directly, or through Push Hub.

Example: REST(ful) pushPush request containing a JSON payload. The content-available field is a sub-element of the customParameters element called "apns.contentAvailable", and is of type "boolean". Issue a POST method on:
> POST /restnotification/registration/<<applicationId>> HTTP/1.1
> Accept-Encoding: gzip,deflate
> Content-Type: application/json
> Authorization: Basic cHVzaDpzZWNyZXQ=
> Content-Length: 146
> Host: localhost:8080
> Connection: Keep-Alive
> User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
> {
 "data": "pushTest",
 "customParameters":
 {"apns.contentAvailable":"true" }
}
Example: non-SAP Gateway notification. Include the header "X-SMP-APNS-CONTENT-AVAILABLE". Issue a POST method on:
> POST /Notification/<<applicationId>> HTTP/1.1
> Accept-Encoding: gzip,deflate
> Content-Type: application/xml
> Authorization: Basic cHVzaDpzZWNyZXQ=
> X-SMP-APNS-CONTENT-AVAILABLE: true
> X-SMP-APNS-DATA: pushTest
> Content-Length: 0
> Host: localhost:8080
> Connection: Keep-Alive
> User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
Example: SAP Gateway notification Include the header "X-SAP-POKE-CONTENT-AVAILABLE". Issue a POST method on:
> POST /Notification/<<applicationId>> HTTP/1.1
> Accept-Encoding: gzip,deflate
> Content-Type: application/xml
> Authorization: Basic cHVzaDpzZWNyZXQ=
> X-SAP-POKE-DATA: pushTest
> X-SAP-POKE-CONTENT-AVAILABLE: true
> Content-Length: 0
> Host: localhost:8080
> Connection: Keep-Alive
> User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
Example: URL parameter encoded. Append the parameter "Content_Available=" to the request URL. Issue a POST method on:
> POST /Notification/<<applicationId>>?alert=PushAlert&data=pushTest&Content_Available=true HTTP/1.1
> Accept-Encoding: gzip,deflate
> Content-Type: application/xml
> Authorization: Basic cHVzaDpzZWNyZXQ=
> Content-Length: 0
> Host: localhost:8080
> Connection: Keep-Alive
> User-Agent: Apache-HttpClient/4.1.1 (java 1.5)