post https://onesignal.com/api/v1/players
Register a new device to one of your OneSignal apps
Not Recommended, use the SDK instead
This API endpoint is designed to be used from our open source Mobile and Web Push SDKs. It is not designed for developers to use it directly. See
Onboarding With OneSignal.If you use this method instead of our SDKs, many OneSignal features such as conversion tracking, timezone tracking, language detection, and rich-push won't work out of the box. It will also make it harder to identify possible setup issues.
This method is used to register a new device with OneSignal.
If a device is already registered with the specified identifier, then this will update the existing device record instead of creating a new one.
The returned ID is for the OneSignal Device Channel Record. If you set device_type = 11 the returned ID is for the Email Channel associated with the device. device_type = 14 is the SMS Channel. All other device_type correspond to the Push Channel. It is recommended to include an external_user_id to associate all Device Channel Records with your own User ID.
iOS
Must set
test_typeto1when building your iOS app as development. Omit this field in your production app builds.
Body Parameters - Add a device
| Parameter | Type | Description |
|---|---|---|
app_id | String | Required Your OneSignal App Id found in Keys & IDs. |
device_type | Int | Required The device's platform:0 = iOS1 = Android2 = Amazon3 = WindowsPhone (MPNS)4 = Chrome Apps / Extensions5 = Chrome Web Push6 = Windows (WNS)7 = Safari8 = Firefox9 = MacOS10 = Alexa11 = Email13 = For Huawei App Gallery Builds SDK Setup. Not for Huawei Devices using FCM14 = SMS |
identifier_auth_hash | String | Only required if you have enabled Identity Verification and device_type is 11 (Email) or 14 SMS (coming soon). |
identifier | String | Recommended: For Push Notifications, this is the Push Token Identifier from Google or Apple. For Apple Push identifiers, you must strip all non alphanumeric characters. Examples: iOS: 7abcd558f29d0b1f048083e2834ad8ea4b3d87d8ad9c088b33c132706ff445f0Android: APA91bHbYHk7aq-Uam_2pyJ2qbZvqllyyh2wjfPRaw5gLEX2SUlQBRvOc6sck1sa7H7nGeLNlDco8lXj83HWWwzV...Email Addresses: set the full email address [email protected] and make sure to set device_type to 11.Phone Numbers: set the E.164 format and make sure to set device_type to 14. |
test_type | Int | This is used in deciding whether to use your iOS Sandbox or Production push certificate when sending a push when both have been uploaded. Set to the iOS provisioning profile that was used to build your app.1 = Development2 = Ad-HocOmit this field for App Store builds. |
language | String | Recommended Language code. Typically lower case two letters, except for Chinese where it must be one of zh-Hans or zh-Hant. Example: en |
timezone | Int | Recommended Number of seconds away from UTC. Example: -28800 |
game_version | String | Recommended Version of your app. Example: 1.1 |
device_model | String | Recommended Device make and model. Example: iPhone5,1 |
device_os | String | Recommended Device operating system version. Example: 7.0.4 |
ad_id | String | The ad id for the device's platform: Android = Advertising Id iOS = identifierForVendor WP8.1 = AdvertisingId |
sdk | String | Recommended Name and version of the plugin that's calling this API method (if any) |
session_count | Int | Number of times the user has played the game, defaults to 1 |
tags | Hash | Custom tags for the player. Only support string key value pairs. Does not support arrays or other nested objects. Example: {"foo":"bar","this":"that"} |
amount_spent | String | Amount the user has spent in USD, up to two decimal places |
created_at | Int | Unix timestamp in seconds indicating date and time when the device downloaded the app or subscribed to the website. |
playtime | Int | Seconds player was running your app. |
last_active | Int | Unix timestamp in seconds indicating date and time when the device last used the app or website. |
notification_types | Int | 1 = subscribed-2 = unsubscribediOS - These values are set each time the user opens the app from the SDK. Use the SDK function set Subscription instead. Android - You may set this but you can no longer use the SDK method setSubscription later in your app as it will create synchronization issues. |
long | Double | Longitude of the device, used for geotagging to segment on. |
lat | Double | Latitude of the device, used for geotagging to segment on. |
country | String | Country code in the ISO 3166-1 Alpha 2 format |
external_user_id | String | A custom user ID |
external_user_id_auth_hash | String | Only required if you have enabled Identity Verification and device_type is NOT 11 email. |
Example Code - Add a device
curl --include \
--request POST \
--header "Content-Type: application/json" \
--data-binary "{\"app_id\" : \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\",
\"identifier\":\"ce777617da7f548fe7a9ab6febb56cf39fba6d382000c0395666288d961ee566\",
\"language\":\"en\",
\"timezone\":-28800,
\"game_version\":\"1.0\",
\"device_os\":\"7.0.4\",
\"device_type\":0,
\"device_model\":\"iPhone 8,2\",
\"tags\":{\"a\":\"1\",\"foo\":\"bar\"}}" \
https://onesignal.com/api/v1/players
<?PHP
$fields = array(
'app_id' => "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
'identifier' => "ce777617da7f548fe7a9ab6febb56cf39fba6d382000c0395666288d961ee566",
'language' => "en",
'timezone' => "-28800",
'game_version' => "1.0",
'device_os' => "9.1.3",
'device_type' => "0",
'device_model' => "iPhone 8,2",
'tags' => array("foo" => "bar")
);
$fields = json_encode($fields);
print("\nJSON sent:\n");
print($fields);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://onesignal.com/api/v1/players");
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_POST, TRUE);
curl_setopt($ch, CURLOPT_POSTFIELDS, $fields);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
$response = curl_exec($ch);
curl_close($ch);
$return["allresponses"] = $response;
$return = json_encode( $return);
print("\n\nJSON received:\n");
print($return);
print("\n");
?>
Result Format - Add a device
{"success": true, "id": "ffffb794-ba37-11e3-8077-031d62f86ebf" }