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 mobile user, then you must be a member of the realm 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 the MobileEnvironment_Notifications
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 that's associated with this device instance. This can be set only by users with the `MobileEnvironment_Notifications` 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",
"platform":"IOS",
"version":"1.0"
},
"notificationToken":"03767dea-29ac-4440-b4f6-75a755845ade",
"notificationProvider":"APNS"
}
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.
{
"id":"8a8a1eff-83c3-41b4-bea8-33357962d9a7",
"modifiedOn":"2015-05-05'T'12:09:33.281'Z",
"mobileClient":{
"id":"com.oracle.myapplication",
"platform":"IOS",
"version":"1.0"
},
"user":"joe",
"notificationToken":"03767dea-29ac-4440-b4f6-75a755845ade",
"notificationProvider":"APNS"
}
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
Mobile Cloud Service error code.
-
o:errorDetails(optional):
array o:errorDetails
Minimum Number of Items:
0
List of the issues that cause the error. 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
The URI to the link that provides more detailed information about the error.
-
o:errorCode:
string
Mobile Cloud Service 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.
{
"title":"Cannot call API",
"detail":"Unable to use API virtualization for calls without any Mobile Backend context.",
"status":400,
"o:errorCode":"MOBILE-58060",
"o:errorPath":"/mobile/platform/devices/register",
"o:ecid":"cde040005cd5983e:4372d958:14c8c4c2d6c:-8000-000000000032b9d5, 0",
"type":"http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1"
}
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 doesn't have theMobileEnvironment_Notifications
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
Mobile Cloud Service error code.
-
o:errorDetails(optional):
array o:errorDetails
Minimum Number of Items:
0
List of the issues that cause the error. 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
The URI to the link that provides more detailed information about the error.
-
o:errorCode:
string
Mobile Cloud Service 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.
{
"title":"Unauthorized",
"detail":"401 - Unauthorized",
"status":401,
"o:errorCode":"MOBILE-15209",
"o:errorPath":"/mobile/platform/devices/register",
"o:ecid":"cde040005cd5983e:4372d958:14c8c4c2d6c:-8000-000000000033b51c, 0",
"type":"http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1"
}
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
Mobile Cloud Service error code.
-
o:errorDetails(optional):
array o:errorDetails
Minimum Number of Items:
0
List of the issues that cause the error. 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
The URI to the link that provides more detailed information about the error.
-
o:errorCode:
string
Mobile Cloud Service 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.
{
"title":"Mobile Backend not found",
"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.",
"status":404,
"o:errorCode":"MOBILE-58026",
"o:errorPath":"/mobile/platform/devices/register",
"o:ecid":"cde040005cd5983e:4372d958:14c8c4c2d6c:-8000-000000000033b529, 0",
"type":"http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1"
}
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
Mobile Cloud Service error code.
-
o:errorDetails(optional):
array o:errorDetails
Minimum Number of Items:
0
List of the issues that cause the error. 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
The URI to the link that provides more detailed information about the error.
-
o:errorCode:
string
Mobile Cloud Service 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.
{
"title":"Unsupported media type",
"detail":"The MIME media type isn't supported, only application/json is supported. Specify a media type that is supported.",
"status":415,
"o:errorCode":"MOBILE-92515",
"o:errorPath":"/mobile/platform/devices/register",
"o:ecid":"cde040005cd5983e:4372d958:14c8c4c2d6c:-8000-000000000033ba73, 0",
"type":"http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1"
}
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.
curl -i
-X POST
-u mobile.user@example.com:mypass
-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 registered with the platform vendor (Apple in this case). For Android, this is the package name, and for iOS, this is the app's bundle ID.
{
"notificationToken": "b14d6dfbd9d56e09f098",
"mobileClient": {
"id": "my.app.id",
"version": "1.0",
"platform": "IOS"
},
"notificationProvider": "APNS"
}
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: Mon, 30 Apr 2018 21:17:40 GMT
Content-Length: 260
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",
"version": "1.0",
"platform": "IOS"
},
"modifiedOn": "2018-04-30T21:17:40.160Z",
"links": []
}