LATEST VERSION: 1.9 - CHANGELOG
Push Notification Services v1.9

Registration

GET /v1/registration/:deviceUuid

Retrieves a device’s registration for a specific platform.

Authentication: HTTP Basic platform_uuid:platform_secret

Query Parameters: None

Response Data, status: 200 (OK)

{
  "os": "",                     # one of [ios|android|android-fcm|android-baidu]
  "device_model": "",           # device model identifier
  "device_manufacturer": "",    # device manufacturer identifier
  "device_alias": "",           # application specific device/user identifier
  "device_uuid": "",            # unique device identifier
  "registration_token": "",     # token provided by APNS (ios), GCM (android), FCM (android-fcm), or Baidu (android-baidu)
  "tags": [                     # tags the device/user is subscribed to, this will overwrite any existing tags the device/user was previously subscribed to
    {
      "text": ""
    }
  ],
  "active": "",                 # can the device be targeted for pushes
  "os_version": ""              # device version string
}

GET /v1/registration/count/

Returns the total number of device registrations that have been stored for one platform.

Authentication: HTTP Basic platform_uuid:platform_secret

Query Parameters: None

Response Data, status: 200 (OK)

Returns an integer.


POST /v1/registration/

Register a device to an app release. The response will include device_uuid. You should save this identifier, as other registration endpoints will require it (ex. DELETE).

When the environment variable push_security_verifyCustomUserId is set to true (which is default), creating a registration with a custom_user_id, it is required that the custom_user_id is encrypted with a unique HMAC using the device shared secret as the cryptigraphic key.

For more information see Registering with a Custom User ID.

Authentication: HTTP Basic platform_uuid:platform_secret

Query Parameters: None

Request Body:

{
  "device_alias": "string",               # application specific device/user identifier. We recommend that you use the user's device name as device alias
  "device_model": "string",               # device model identifier
  "device_manufacturer": "string",        # device manufacturer identifier
  "os": "string",                         # device os, one of [ios|android|android-fcm|android-baidu]
  "os_version": "string",                 # device version string
  "registration_token": "string",         # token provided by APNS (ios), GCM (android), FCM (android-fcm), or Baidu (android-baidu)
  "tags": [ "tag1", "tag2" ],             # tags the device/user is subscribed to, this will overwrite any existing tags the device/user was previously subscribed to
  "custom_user_id": "string"              # allows you to register a device under an ID that is meaningful to your system such as their login
}

Response Data, status: 200 (OK)

{
  "os_version": "",           # os version string
  "tags": [                   # tags that the device has subscribed to
    {
      "text": "tag1"
    },
    {
      "text": "tag2"
    }
  ],
  "os": "",                   # one of [ios|android|android-fcm|android-baidu]
  "device_model": "",         # device model identifier
  "device_manufacturer": "",  # device manufacturer identifier
  "device_alias": "",         # application specific device/user identifier
  "device_uuid": "",          # the unique identifier assigned to the device by Push Notifications
  "registration_token": "",   # token provided by APNS (ios), GCM (android), FCM (android-fcm), or Baidu (android-baidu)
  "active": "",               # can the device be targeted for pushes
  "custom_user_id": ""        # device registered with custom user id
}

LIMITS

Registering a device is bounded by the following limits per request:

  • Devices: Auto-Generated
  • Custom User Ids: 1
  • Tags: 1024

Examples:

  • Register a device:
  {
    "device_alias": "John's iPhone",
    "device_model": "iPhone 6",
    "device_manufacturer": "Apple",
    "os": "ios",
    "os_version": "9.0",
    "registration_token": "b50edac575bfba07dd019b28b2af7189a3ddda17c806ef14a9abbfd00533f67e",
    "tags": [ "beta", "gamma", "alpha" ],
    "custom_user_id": "jsmith"
  }

PUT /v1/registration/:device_uuid

Update a registration. Requires that the device_uuid returned when you registered is sent as a url parameter.

When the environment variable push_security_verifyCustomUserId is set to true (which is default), updating a registration with a custom_user_id, it is required that the custom_user_id is encrypted with a unique HMAC using the device shared secret as the cryptigraphic key.

Authentication: HTTP Basic platform_uuid:platform_secret

Query Parameters: None

Request Body:

{
  "device_alias": "string",           # application specific device/user identifier. We recommend that you use the user's device name as device alias.
  "device_manufacturer": "string",    # device manufacturer identifier
  "device_model": "string",           # device model identifier
  "os_version": "string",             # os version string
  "registration_token": "string",     # token provided by APNS (ios), GCM (android), FCM (android-fcm), or Baidu (android-baidu)
  "tags": {
    "subscribe": ["tag1","tag2"],     # add new tags subscriptions to the device/user
    "unsubscribe": ["tag3","tag4"]    # remove tags that the device/user is subscribed to
  },
  "custom_user_id": "string"          # allows you to register a device under an ID that is meaningful to your system such as their login
}

Examples:

  • Update device registration:
  {
    "device_alias": "John Smith's iPhone",
    "device_model": "iPhone 6",
    "device_manufacturer": "Apple",
    "os": "ios",
    "os_version": "9.0",
    "registration_token": "b50edac575bfba07dd019b28b2af7189a3ddda17c806ef14a9abbfd00533f67e",
    "tags": [ "beta", "gamma", "alpha", "delta" ],
    "custom_user_id": "john.smith"
  }

DELETE /v1/registration/:device_uuid

Delete a registration. Requires that the device_uuid returned when you registered is sent as a url parameter

Authentication: HTTP Basic platform_uuid:platform_secret

Query Parameters: None

Request Body:

None.

Response Data, status: 204 (NO CONTENT)

Create a pull request or raise an issue on the source for this page in GitHub