Register Mobile Client
/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
- application/json
object
A mobile client instance.
-
mobileClient:
object mobileClient
-
notificationProvider(optional):
Allowed Values:
[ "APNS", "GCM", "FCM", "WNS", "SYNIVERSE" ]
The notification service the notification token is for. -
notificationToken:
string
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.
-
user(optional):
string
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
object
-
id(optional):
string
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`
-
platform(optional):
Allowed Values:
[ "IOS", "ANDROID", "WINDOWS", "WEB" ]
Indicates whether the mobile client is running on iOS, Android, Windows, or Web. -
version(optional):
string
The version of the mobile client that will receive the notifications.
{
"mobileClient":{
"id":"com.oracle.myapplication",
"version":"1.0",
"platform":"IOS"
},
"notificationProvider":"APNS",
"notificationToken":"03767dea-29ac-4440-b4f6-75a755845ade"
}
Response
- application/json
201 Response
object
A mobile client instance.
-
consentStatus(optional):
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. -
id(optional):
string
The unique identifier of the device.
-
mobileClient:
object mobileClient
-
modifiedOn:
string
Pattern:
yyyy-MM-dd'T'HH:mm:ss.SSS'Z'
The date and time that the device was registered. -
notificationProvider(optional):
Allowed Values:
[ "APNS", "GCM", "FCM", "WNS", "SYNIVERSE" ]
The notification service that the `notificationToken` is for. -
notificationToken:
string
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.
-
user(optional):
string
The user name for the user that's associated with this device instance.
object
-
id(optional):
string
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`
-
platform(optional):
Allowed Values:
[ "IOS", "ANDROID", "WINDOWS", "WEB" ]
Indicates whether the mobile client is running on iOS, Android, Windows, or Web. -
version(optional):
string
The version of the mobile client that will receive the notifications.
{
"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.
-
Content-Type: string
The media type of message, which is
application/json
.
object
Error
-
detail:
string
Message that provides the error details.
-
o:ecid:
string
Execution context ID, which is a unique identifier to correlate events or requests that are associated with the same transaction across several components.
-
o:errorCode:
string
The service's error code.
-
o:errorDetails(optional):
array o:errorDetails
Minimum Number of Items:
0
Included when the error is caused by multiple issues. -
o:errorPath:
string
The relative point in the API path where the error occurred.
-
status:
integer
HTTP status code. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html for more details.
-
title:
string
Summary of the problem.
-
type:
string
The URI to the link that provides details about the HTTP status code.
array
0
-
Array of:
object Error Detail
Title:
Error Detail
object
Error Detail
-
instance:
string
URI to the link that provides more detailed information about the error.
-
o:errorCode:
string
The service's error code.
-
o:errorPath:
string
The relative point in the API path where the error occurred.
-
title:
string
Summary of the problem.
-
type:
string
The URI to the link that provides details about the HTTP status code.
{
"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 theAdministrator
orDeveloper
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.
-
Content-Type: string
The media type of error message, which is
application/json
.
object
Error
-
detail:
string
Message that provides the error details.
-
o:ecid:
string
Execution context ID, which is a unique identifier to correlate events or requests that are associated with the same transaction across several components.
-
o:errorCode:
string
The service's error code.
-
o:errorDetails(optional):
array o:errorDetails
Minimum Number of Items:
0
Included when the error is caused by multiple issues. -
o:errorPath:
string
The relative point in the API path where the error occurred.
-
status:
integer
HTTP status code. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html for more details.
-
title:
string
Summary of the problem.
-
type:
string
The URI to the link that provides details about the HTTP status code.
array
0
-
Array of:
object Error Detail
Title:
Error Detail
object
Error Detail
-
instance:
string
URI to the link that provides more detailed information about the error.
-
o:errorCode:
string
The service's error code.
-
o:errorPath:
string
The relative point in the API path where the error occurred.
-
title:
string
Summary of the problem.
-
type:
string
The URI to the link that provides details about the HTTP status code.
{
"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.
-
Content-Type: string
The media type of error message, which is
application/json
.
object
Error
-
detail:
string
Message that provides the error details.
-
o:ecid:
string
Execution context ID, which is a unique identifier to correlate events or requests that are associated with the same transaction across several components.
-
o:errorCode:
string
The service's error code.
-
o:errorDetails(optional):
array o:errorDetails
Minimum Number of Items:
0
Included when the error is caused by multiple issues. -
o:errorPath:
string
The relative point in the API path where the error occurred.
-
status:
integer
HTTP status code. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html for more details.
-
title:
string
Summary of the problem.
-
type:
string
The URI to the link that provides details about the HTTP status code.
array
0
-
Array of:
object Error Detail
Title:
Error Detail
object
Error Detail
-
instance:
string
URI to the link that provides more detailed information about the error.
-
o:errorCode:
string
The service's error code.
-
o:errorPath:
string
The relative point in the API path where the error occurred.
-
title:
string
Summary of the problem.
-
type:
string
The URI to the link that provides details about the HTTP status code.
{
"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.
-
Content-Type: string
The media type of the error message, which is
application/json
.
object
Error
-
detail:
string
Message that provides the error details.
-
o:ecid:
string
Execution context ID, which is a unique identifier to correlate events or requests that are associated with the same transaction across several components.
-
o:errorCode:
string
The service's error code.
-
o:errorDetails(optional):
array o:errorDetails
Minimum Number of Items:
0
Included when the error is caused by multiple issues. -
o:errorPath:
string
The relative point in the API path where the error occurred.
-
status:
integer
HTTP status code. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html for more details.
-
title:
string
Summary of the problem.
-
type:
string
The URI to the link that provides details about the HTTP status code.
array
0
-
Array of:
object Error Detail
Title:
Error Detail
object
Error Detail
-
instance:
string
URI to the link that provides more detailed information about the error.
-
o:errorCode:
string
The service's error code.
-
o:errorPath:
string
The relative point in the API path where the error occurred.
-
title:
string
Summary of the problem.
-
type:
string
The URI to the link that provides details about the HTTP status code.
{
"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", "notificationProvider: "APNS", "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", "notificationProvider": "SYNIVERSE" "mobileClient": { "id": "an.app", "version": "1.0", "platform": "WEB" }}
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 a service-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", "notificationProvider: "APNS", "mobileClient": { "id": "my.app.id", "user": "joe", "version": "1.0", "platform": "IOS" }, "modifiedOn": "2015-06-17T18:37:59.424Z" }