1. REST API Reference for Oracle Mobile Cloud Enterprise - Platform APIs
  2. Tasks
  3. Mobile Devices

Register Mobile Client

post

/mobile/platform/devices/register

Registers the mobile client instance that receives notifications.

Permissions

You can access this operation as a social user, a virtual user, an anonymous user, or a mobile user. If you access this operation as a virtual user or a mobile user, then you must have the role that's associated with the mobile backend.

You can set the user property in the request body only if you are a team member with either the Developer or Administrator role.

Request

Supported Media Types
Body ()
Root Schema : A mobile client instance.
Type: object
Title: A mobile client instance.
Show Source
  • mobileClient
  • Allowed Values: [ "APNS", "GCM", "FCM", "WNS", "SYNIVERSE" ]
    The notification service the notification token is for.
  • Token needed by the push notification service for sending calls. This token uniquely identifies the specific instance of a mobile application associated with a specific device, and is used to ensure that notifications are sent to the correct recipient. Encode in hexadecimal if necessary.
  • The user name for the user associated with this device instance. This can be set only by team members with either the `Administrator` or `Developer` role
Nested Schema : mobileClient
Type: object
Show Source
  • Identify the mobile client that will receive the notifications. This is the application ID that you registered the application with in the mobile backend's Settings tab, such as `com.mycompany.appname`
  • Allowed Values: [ "IOS", "ANDROID", "WINDOWS", "WEB" ]
    Indicates whether the mobile client is running on iOS, Android, Windows, or Web.
  • The version of the mobile client that will receive the notifications.
Example Request (application/json)
{
    "mobileClient":{
        "id":"com.oracle.myapplication",
        "version":"1.0",
        "platform":"IOS"
    },
    "notificationProvider":"APNS",
    "notificationToken":"03767dea-29ac-4440-b4f6-75a755845ade"
}

Response

Supported Media Types

201 Response

The device has been registered successfully and can receive notifications.
Body ()
Root Schema : A mobile client instance.
Type: object
Title: A mobile client instance.
Show Source
  • Allowed Values: [ "NONE", "OPTIN" ]
    This property is included when consent management is enabled in the Syniverse client profile for the client and platform. This property indicates the current consent status for the registered phone number (`notificationToken` value). The possible values are `NONE`, which indicates that the service is waiting for a user response on the Synaverse channel, and `OPTIN`, which indicates that user has given consent. Note that when a user opts out, the service deregisters the device.
  • The unique identifier of the device.
  • mobileClient
  • Pattern: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'
    The date and time that the device was registered.
  • Allowed Values: [ "APNS", "GCM", "FCM", "WNS", "SYNIVERSE" ]
    The notification service that the `notificationToken` is for.
  • Token needed by the push notification service for sending calls. This token uniquely identifies the specific instance of a mobile application associated with a specific device, and is used to ensure that notifications are sent to the correct recipient. Encode in hexadecimal if necessary.
  • The user name for the user that's associated with this device instance.
Nested Schema : mobileClient
Type: object
Show Source
  • Identifies the mobile client that will receive the notifications. This is the application ID that you registered the application with in the mobile backend's Settings tab, such as `com.mycompany.appname`
  • Allowed Values: [ "IOS", "ANDROID", "WINDOWS", "WEB" ]
    Indicates whether the mobile client is running on iOS, Android, Windows, or Web.
  • The version of the mobile client that will receive the notifications.
Example Response (application/json)
{
    "modifiedOn":"2017-05-11T05:53:45.334Z",
    "mobileClient":{
        "id":"com.oracle.myapplication",
        "version":"1.0",
        "platform":"IOS"
    },
    "id":"8a8a1eff-83c3-41b4-bea8-33357962d9a7",
    "user":"joe",
    "notificationProvider":"APNS",
    "notificationToken":"03767dea-29ac-4440-b4f6-75a755845ade"
}

400 Response

The operation cannot be performed due to one of the following reasons:

  • The mobile client ID isn't valid or isn't registered with the mobile backend.
  • You used Basic authorization, and the Oracle-Mobile-Backend-ID HTTP request header was not specified.
  • The body isn't a correctly formed JSON object or a required property is missing.
  • The notification provider isn't valid.
  • The mobile client doesn't have a profile for the specified notification provider.
  • The mobile client requires consent management, and there's a problem with the channel (sender) ID that's associated with the client profile.
  • The mobile client requires consent management, and the number being registered was recently opted out.
Headers
Body ()
Root Schema : Error
Type: object
Title: Error
The error JSON object returned by the service.
Show Source
Nested Schema : o:errorDetails
Type: array
Minimum Number of Items: 0
List of the issues that cause the error. Included when the error is caused by multiple issues.
Show Source
Nested Schema : Error Detail
Type: object
Title: Error Detail
Show Source
Example Response (application/json)
{
    "o:errorCode":"MOBILE-58060",
    "detail":"Unable to use API virtualization for calls without any Mobile Backend context.",
    "type":"http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1",
    "title":"Cannot call API",
    "o:errorPath":"/mobile/platform/devices/register",
    "o:ecid":"cde040005cd5983e:4372d958:14c8c4c2d6c:-8000-000000000032b9d5, 0",
    "status":400
}

401 Response

User is unauthorized to perform this call. This can happen due to one of the following reasons:

  • The user property was included in the request body but the current user is not a team member with either the Administrator or Developer role.
  • The user doesn't exist.
  • The password is incorrect.
  • The credentials weren't encoded using the RFC2045-MIME variant of Base64.
  • The Authorization HTTP request header wasn't specified.
Headers
Body ()
Root Schema : Error
Type: object
Title: Error
The error JSON object returned by the service.
Show Source
Nested Schema : o:errorDetails
Type: array
Minimum Number of Items: 0
List of the issues that cause the error. Included when the error is caused by multiple issues.
Show Source
Nested Schema : Error Detail
Type: object
Title: Error Detail
Show Source
Example Response (application/json)
{
    "o:errorCode":"MOBILE-15209",
    "detail":"401 - Unauthorized",
    "type":"http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1",
    "title":"Unauthorized",
    "o:errorPath":"/mobile/platform/devices/register",
    "o:ecid":"cde040005cd5983e:4372d958:14c8c4c2d6c:-8000-000000000033b51c, 0",
    "status":401
}

404 Response

The operation cannot be performed because we cannot find the active mobile backend.

Headers
Body ()
Root Schema : Error
Type: object
Title: Error
The error JSON object returned by the service.
Show Source
Nested Schema : o:errorDetails
Type: array
Minimum Number of Items: 0
List of the issues that cause the error. Included when the error is caused by multiple issues.
Show Source
Nested Schema : Error Detail
Type: object
Title: Error Detail
Show Source
Example Response (application/json)
{
    "o:errorCode":"MOBILE-58026",
    "detail":"We cannot find the active mobile backend for the given clientId fd4cc0cf-0a72-4ed6-aab6-295133b8904e and BASIC schema. Specify a valid clientId and try again.",
    "type":"http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1",
    "title":"Mobile Backend not found",
    "o:errorPath":"/mobile/platform/devices/register",
    "o:ecid":"cde040005cd5983e:4372d958:14c8c4c2d6c:-8000-000000000033b529, 0",
    "status":404
}

415 Response

The MIME media type isn't supported or was not specified. Only application/json is supported.

Headers
Body ()
Root Schema : Error
Type: object
Title: Error
The error JSON object returned by the service.
Show Source
Nested Schema : o:errorDetails
Type: array
Minimum Number of Items: 0
List of the issues that cause the error. Included when the error is caused by multiple issues.
Show Source
Nested Schema : Error Detail
Type: object
Title: Error Detail
Show Source
Example Response (application/json)
{
    "o:errorCode":"MOBILE-92515",
    "detail":"The MIME media type isn't supported, only application/json is supported. Specify a media type that is supported.",
    "type":"http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1",
    "title":"Unsupported media type",
    "o:errorPath":"/mobile/platform/devices/register",
    "o:ecid":"cde040005cd5983e:4372d958:14c8c4c2d6c:-8000-000000000033ba73, 0",
    "status":415
}

Examples

The following example shows how to register an instance of a mobile app on a mobile device for notifications by submitting a POST request on the REST resource using cURL. For more information about cURL, see Use cURL. 

curl -i
-X POST 
-u mobile.user@example.com:password
-d @register.json
-H "Content-Type: application/json; charset=utf-8"
-H "Oracle-Mobile-Backend-ID: ABCD9278-091f-41aa-9cb2-184bd0586fce"
https://fif.cloud.oracle.com/mobile/platform/devices/register

Examples of Request Bodies

The following shows an example of the request body for a mobile client on the iOS platform. The notificationToken, which is the device ID that was obtained from Apple Push Notifications Service (APNS), uniquely identifies the specific instance of a mobile app that is associated with a specific device. The mobileClient:id is the app ID that was entered when the mobile app was registered with the mobile backend. This is the ID that was registered with the platform vendor (Apple in this case). 

{
  "notificationToken": "b14d6dfbd9d56e09f098",
  "mobileClient": {
    "id": "my.app.id",
    "version": "1.0",
    "platform": "IOS"
  }
}

This example shows the request body for a mobile client on the Web platform. In this example, the notificationToken is the device ID that was obtained from notification provider Syniverse. 

{
  "notificationToken": "+15551111212",
  "mobileClient": {
    "id": "an.app",
    "version": "1.0",
    "platform": "WEB"
  },
  "notificationProvider": "SYNIVERSE"
}

Example of Response Header

The following shows an example of the response header:

201 CREATED
Content-Type: application/json
Date: Wed, 17 Jun 2015 18:37:58 GMT
Location: /mobile/platform/devices/27fee547-bdd0-4688-9497-475ec5ed0dfd
Oracle-Mobile-Runtime-Version: 15.4.1-201506162222

Example of Response Body

The following example shows the contents of the response body in JSON format, including an MCS-generated unique ID for the registered device (that is, the instance of the mobile app on the mobile device):

{
  "id": "27fee547-bdd0-4688-9497-475ec5ed0dfd",
  "notificationToken": "b14d6dfbd9d56e09f098",
  "mobileClient": {
    "id": "my.app.id",
    "user": "joe",
    "version": "1.0",
    "platform": "IOS"
  },
  "modifiedOn": "2015-06-17T18:37:59.424Z"
}