Child pages
  • PushNotification
Skip to end of metadata
Go to start of metadata

Description

The PushNotification API allows to send notification alerts to all devices subscribed in a particular channel, or to a set of devices that is defined when calling the API (this is called "ad-hoc" push). When sending a notification through a channel, the caller needs to fill the following parameters: "channelId", "notification" and "fireAndForget" (optional). If the caller rather wishes to send a notification to an arbitrary set of device tokens, he should fill the following parameters: "notification", "adhoc.tokens", "adhoc.platform", "adhoc.applicationID". 

The PushNotification API can be called over HTTP (i.e. does not need to be called over HTTPS as it is the case for the other push notification APIs). Notifications can be sent synchronously or asynchronously. In case the targeted platform is "iOS", the notifications are pushed to the APNS server which then sends the notification to all the specific devices. In case the targeted platform is "Android", the notifications are sent to GCM server which then sends the notification to all the specific devices.

 What are Push Notifications?

Apstrata allows a developer to send push notifications to iOS applications by abstracting the Apple Push Notification Service. Similarly, it allows a developer to send push notifications to Android applications by abstracting the Google Cloud Messaging for Android. In other words, apstrata serves as a push notifications provider for iOS and Andriod applications.

Apstrata makes it really simple to enable push notifications for your applications through a REST API. Here are the steps that need to be taken for this purpose:

  1. Create a configuration for a "mobile application" using the "AddCertificate" API (upload the required certificate and password as both Apple and Google require that push notifications requests be authenticated).
  2. Create channels and subscribe device tokens to them (every device has a unique token or identifier) or push notifications to a run-time specified set of devices ("ad-hoc")
  3. Send notifications to a channel (push notifications will be sent to all devices subscribed in the channel) or to the ad-hoc set of tokens

When pushing notifications, tokens that do not correspond to real devices will be automatically tagged as invalid.

In case the notification is sent in asynchronous mode, a log document will be created with the document key being the request id returned in the response of the PushNotification call. This log document will contain the results of pushing the notification to the specific devices, such as invalid tokens and error messages. You can get this document by querying for it using the previously mentioned request id as the apsdb.documentKey parameter value.

Specific Request Parameters

(Refer to Common Request Parameters)

Name

Description

Required

Default

Possible Values

apsdb.store

The name of the store in which the channel is created

No

DefaultStore

 

channelIdA unique identifier for the channelYes  

notification

The payload embracing the notification message to be sent. For iOS payload details, please refer to

http://developer.apple.com/library/mac/#documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/ApplePushService.html#//apple_ref/doc/uid/TP40008194-CH100-SW1

For Android, the payload needs to be sent in the following format {"key1":"value1","key2":"value2", ...}

Yes

 

 

fireAndForgetA boolean indicating whether to send the notification in synchronous or asynchronous mode. If set to true, then the mode is asynchronousNotruetrue
false 
adhoc.tokensA array of device tokens. Fill this parameter when you do not want to push a notification through a channel, but rather to an arbitrary set of devices.No  
adhoc.platformThe targeted platform, i.e. the platform of the devices (iOS or Android).  Fill this parameter when you do not want to push a notification through a channel, but rather to an arbitrary set of devices.No "Android", "iOS"
adhoc.applicationIDThe identifier of the mobile application (as created in Apstrata using the "AddCertificate" API). Fill this parameter when you do not want to push a notification through a channel, but rather to an arbitrary set of devices.No  
adhoc.lifeTimeThe time in seconds before a notification expires. Can be a negative number. Please refer to the documentation of the respective services (APNS and Google) for more on this value. Fill this parameter when you do not want to push a notification through a channel, but rather to an arbitrary set of devices.No 5

Specific Response Elements

(Refer to Common Response Elements)

The following specific "result" element is a child of the common root element "response" and a sibling of the common "metadata" element:

{
	"result": {
		"invalidDeviceTokens": [
			{
				"channelId": "the id of the channel",
				"deviceToken": "the id of a device",
				"platform": "the platform of the channel",
				"status": "the status returned from pushing the notification to this device",
				"message": "the error message returned from pushing the notification to this device",
				"specificAttributes": [an array of JSON objects corresponding to specific platform attributes]
			},
	 		{
				"channelId": "the id of the channel",
				"deviceToken": "the id of another device",
				"platform": "the platform of the channel",
				"status": "the status returned from pushing the notification to this device",
				"message": "the error message returned from pushing the notification to this device",
				"specificAttributes": [an array of JSON objects corresponding to specific platform attributes]
			}
		]
	}
}

If the notification was pushed to iOS platforms, the specificAttributes array will contain "command : command_value", "status :  status_value" and "identifier : identifier_valuei" as returned by APNS (for more on what is returned by APNS, please refer to http://developer.apple.com/library/ios/#DOCUMENTATION/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingWIthAPS/CommunicatingWIthAPS.html)

If the notification was pushed to Android platforms, the specificAttributes array will contain "usedToken : the_auth_token_that_was_used_to_push_the_notification", "updatedToken : empty_or_a_new_auth_token_sent_by_GCM". Concerning this latter attribute, note that GCM periodically refreshes the authentication token of a mobile application and this is transparently tackled by the Apstrata Push API. Therefore, when "updatedToken" is not empty, this indicates that the push to the concerned device was successful but that a new auth token was obtained from GCM. This new token will be used for pushing further notifications.

Specific Logical Errors

(Refer to Common Logical Error Codes)

Error

Description

Status Code

INVALID_STORE_NAME

Store name is invalid.

400

STORE_NOT_FOUND

The store was not found

404

PARAMETER_REQUIREDOne of the required parameters is missing400
INVALID_REQUESTThe request is made over HTTP and not HTTPS400
PERMISSION_DENIEDThe request is made by a regular user and not by the account owner403
DOCUMENT_NOT_FOUNDThe channel does not exist400
INVALID_NOTIFICATIONInvalid payload400

 

Examples

Sample Request

Request URL: http://sandbox.apstrata.com/apsdb/rest/[authenticationkey]/PushNotification?apsws.time=[timestamp]&apsws.authSig=[signature] 



iOS POST parameters:

apsdb.store = MyStore
channelId = MyTestChannel
notification = {"aps":{"alert":"[any_text_message]","badge":5,"sound":"default"}} 



Sample XML Response

Success XML:

<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://www.apstrata.com/services/schemas/apstrata_database_response.xsd">
  <metadata>
    <requestId>b5b303e4-b70d-4c88-84de-2a357b512acb</requestId>
    <status>success</status>
    <statusCode>200</statusCode>
  </metadata>
  <result>
    <invalidDeviceTokens>
      <response channelId="xxxxx" deviceToken="ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ" platform="iOS" status="exception_occured" message="Device token cannot be parsed, most likely because it contains invalid hexadecimal characters: For input string: "ZZ" in ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ">
        <specificAttributes/>
      </response>
      <response channelId="xxxxx" deviceToken="DEDECFDA4D01CA3A11C833F97B52DF2A7F210252E21B01FAA73D34639CE0E412" platform="iOS" status="8" message="APNS: [3] Invalid token">
        <specificAttributes>
          <attribute name="command" value="8"/>
          <attribute name="identifier" value="3"/>
        </specificAttributes>
      </response>
    </invalidDeviceTokens>
  </result>
</response>



Failure XML:

<response xmlns="http://www.apstrata.com/services/schemas/apstrata_database_response.xsd">
    <metadata 
        <requestId>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</requestId>
        <status>failure</status>
        <errorCode>[errorCode]</errorCode>
        <errorDetail>[failMsg]</errorDetail>
    </metadata>
</response> 



Sample JSON Response

{"response": {
  "metadata": {
    "requestId": "5d0a2391-4dae-4669-9802-7e8b1e37ff1d",
    "status": "success",
    "statusCode": "200"
  },
  "result": {
    "invalidDeviceTokens": [
      {
        "channelId": "xxxxx",
        "deviceToken": "ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ",
        "platform": "iOS",
        "status": "exception_occured",
        "message": "Device token cannot be parsed, most likely because it contains invalid hexadecimal characters: For input string: \"ZZ\" in ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ",
        "specificAttributes": [
        ]
      },
      {
        "channelId": "xxxxx",
        "deviceToken": "DEDECFDA4D01CA3A11C833F97B52DF2A7F210252E21B01FAA73D34639CE0E412",
        "platform": "iOS",
        "status": "8",
        "message": "APNS: [3] Invalid token",
        "specificAttributes": [
          {
            "name": "command",
            "value": "8"
          },
          {
            "name": "identifier",
            "value": "3"
          }
        ]
      }
    ]
  }
}}


  • No labels