Device API

List of methods for working with devices

registerDevice

/registerDevice

POST https://cp.pushwoosh.com/json/1.3/registerDevice

Called internally from the SDK. Registers device for the application.

Request Body

{
   "status_code":200,
   "status_message":"OK",
   "response": null
}
Example
{
   "request":{
      "application": "XXXXX-XXXXX", // required, Pushwoosh application code
      "push_token": "dec301908b9ba8df85e57a58e40f96f523f4c2068674f5fe2ba25cdc250a2a41", // optional
      "hwid": "1CA68A12-8DAC-4BB7-BEE5-B756288B6D3C", // required, hardware device ID
      "idfa" : "AEBE52E7-03EE-455A-B3C4-E57283966239", // optional
      "timezone": 3600, // optional, offset in seconds
      "device_type": 1, // required, see the possible values below. For emails, use the "emails" params as described below. 
      "email": "email_address@domain.com", // use instead of "hwid" and "push_token" to register the email address for your email project
      "language": "en", // optional, ISO 639-1|639-2 language code
      "userId": "Alex", // optional
      "tags": { // optional, tag values to set for the device registered 
           "StringTag": "string value",
           "IntegerTag": 42,
           "ListTag": ["string1","string2"], // sets the list of values for Tags of List type
           "DateTag": "2015-10-02 22:11", // note the time should be in UTC
           "BooleanTag": true  // valid values are: true, 1, false, 0, null
           },
  
      // system tags, optionals
      "app_version": "1.2.3", 
      "device_model": "Samsung SM-G355H",
      "os_version": "2.3",
  
      // optional encryption keys for chrome/firefox
      "public_key": "BNmDO4BTKEMJqaqprTf7t/HBUd2BQ/orc88cc/scS5CFP6zhQGIHI1/GgRQD8c4kTxTEEF0quvIUiLQqoBY0/Qo=",
      "auth_token": "RlRmCCdGM/s7ouuhjKFzoQ==",
     
      //optional FCM keys for Chrome (for XMPP)
      "fcm_token": "BNmDO4BTKEMJqaqprTf7t/HBUd2BQ/orc88cc/scS5CFP6zhQGIHI1/GgRQD8c4kTxTEEF0quvIUiLQqoBY0/Qo=",
      "fcm_push_set": "RlRmCCdGM/s7ouuhjKFzoQ=="
   }
}

Possible device types:

  • 1 – iOS

  • 3 – Android

  • 7 – OS X

  • 8 – Windows 8

  • 9 – Amazon

  • 10 – Safari

  • 11 – Chrome

  • 12 – Firefox

To register a email subscriber for your app, send the "email": "email_address@domain.com" param in your /registerDevice or /registerEmail request as follows:

Email registration request
{
   "request":{
      "application": "XXXXX-XXXXX", // required, Pushwoosh application code
      "email": "email_address@domain.com", // required, email address to register for your email project
      "language": "en", // optional, ISO 639-1|639-2 language code
      "userId": "Alex", // optional
      "tags": { // optional, tag values to set for the device registered 
           "StringTag": "string value",
           "IntegerTag": 42,
           "ListTag": ["string1","string2"], // sets the list of values for Tags of List type
           "DateTag": "2015-10-02 22:11", // note the time should be in UTC
           "BooleanTag": true  // valid values are: true, 1, false, 0, null
           }
   }
}

Status codes:

PHP
<?php
//see http://gomoob.github.io/php-pushwoosh/register-device.html
use Gomoob\Pushwoosh\Model\Request\RegisterDeviceRequest;

// creates request instance
$request = RegisterDeviceRequest::create()
    ->setDeviceType(DeviceType::1())
    ->setHwid('HWID')
    ->setLanguage('fr')
    ->setPushToken('xxxxxxxx')
    ->setTimezone(3600);

// call '/registerDevice' Web Service
$response = $pushwoosh->registerDevice($request);

if($response->isOk()) {
    print 'Ok, operation successful.';
} else {
    print 'Oups, the operation failed :-('; 
    print 'Status code : ' . $response->getStatusCode();
    print 'Status message : ' . $response->getStatusMessage();
}

unregisterDevice

/unregisterDevice

POST https://go.pushwoosh.com/json/1.3/unregisterDevice

Removes the device's push token. The unregistered device is still counted in Total Devices and can be reached with In-Apps. Called internally from the SDK.

Request Body

{
    "status_code": 200,
    "status_message": "OK",
    "response": null
}
Example
   {
       "request":{
          "application": "XXXXX-XXXXX", // required, Pushwoosh application code
          "hwid": "8f65b16df378e7a6bece9614e1530fb2" // required, hardware device ID used in /registerDevice function call 
       }
    }

For emails call /deleteEmail.

Status codes:

PHP
<?php

// see http://gomoob.github.io/php-pushwoosh/unregister-device.html
use Gomoob\Pushwoosh\Model\Request\UnregisterDeviceRequest;

// creates request instance
$request = UnregisterDeviceRequest::create()->setHwid('HWID');

// call '/unregisterDevice' Web Service
$response = $pushwoosh->unregisterDevice($request);

if($response->isOk()) {
    print 'Ok, operation successful.';
} else {
    print 'Oups, the operation failed :-('; 
    print 'Status code : ' . $response->getStatusCode();
    print 'Status message : ' . $response->getStatusMessage();
}

setTags

/setTags

POST https://go.pushwoosh.com/json/1.3/setTags

Sets tags values for the device. Called from the SDK.

Request Body

{
   "status_code":200,
   "status_message":"OK",
   "response": null
}

The method is called from the SDK. It is possible to call it remotely from your backend, however you need to maintain an up-to-date database of hwid’s on the backend side.

Example
{
   "request":{
      "application": "XXXXX-XXXXX", // required, Pushwoosh application code
      "hwid": "8f65b16df378e7a6bece9614e1530fb2", // required, hardware device ID used in /registerDevice function call
      "tags": { // required
           "StringTag": "string value",
           "IntegerTag": 42,
           "ListTag": ["string1","string2"], // sets the list of values for Tags of List type
           "DateTag": "2015-10-02 22:11", // note the time is in UTC
           "BooleanTag": true,  // valid values are - true, 1, false, 0, null
      }  
   }
}

Increment Integer tag values

To increment a value of the Integer Tag, use the operation parameter with the "increment" value as follows:

{
   "request":{
      "application": "12345-67890", // required, Pushwoosh application code
      "hwid": "21AB7628-F83F-4R9N-CCC0-PO287CS24CA4", // required, hardware device ID used in /registerDevice function call
      "tags": { // required
           "Level": { // Tag name
               "operation": "increment", // overwrites the integer tag in increments of the following value 
               "value": 1 // increment for the tag value
           }  
      }  
   }
}

Decrement Integer tag values

To decrement, use the negative numbers as the value for the "increment" operation (-1, -2, -3,-n):

{
   "request":{
      "application": "12345-67890", // required, Pushwoosh application code
      "hwid": "21AB7628-F83F-4R9N-CCC0-PO287CS24CA4", // required, hardware device ID used in /registerDevice function call
      "tags": { // required
           "Level": { // Tag name
               "operation": "increment", // overwrites the integer tag in decrement of the following value 
               "value": -1 // decrement for the tag value
           }  
      }  
   }
}

Append List tag values

To extend the List Tag with new values, use the operation parameter with the "append" value as follows:

Example
{
  "request": {
    "hwid": "3d124a793575f189a5ca7dfd96e8aafd", // required, hardware device ID used in /registerDevice function call
    "application": "61A79-C09B3", // required, Pushwoosh application code
    "tags": { // required
      "ListTag": { // Tag name
        "operation": "append", // appends following values to the Tag's list of values
        "value": [ // values to append
          "tag2",
          "tag3"
        ]
      }
    }
  }
}

Remove List tag values

To remove some values from the List Tag, use the "remove" operation as follows:

{
   "request":{
      "application": "12345-67890", // required, Pushwoosh application code
      "hwid": "21AB7628-F83F-4R9N-CCC0-PO287CS24CA4", // required, hardware device ID used in /registerDevice function call
      "tags": { // required
           "In-App Product": { // Tag name
               "operation": "remove", // removes the following values from the list tag
               "value": "outwear_02" // value or values to remove
           }
      }  
   }
}

Set tags by UserID

To set tags for all devices associated to a particular User ID, use the "userId" parameter instead of "hwid".

Make sure the tag you're setting values for is user-specific.

Example
{
   "request":{
      "application": "AAAAA-BBBBB", // Pushwoosh app code
      "userId": "some_user", // user ID you'd like to set tags for 
      "tags": { // tags and values to set
           "Language": "es"

      }  
   }
}

For emails call /setEmailTags.

Status codes:

PHP
<?php
//see http://gomoob.github.io/php-pushwoosh/set-tags.html
use Gomoob\Pushwoosh\Model\Request\SetTagsRequest;

// Creates the request instance
$request = SetTagsRequest::create()
    ->setTags(
        array(
            'StringTag' => 'string value',
            'IntegerTag' => 'integer value',
            'ListTag' => ['string1', 'string2']
        )
    )
    ->setHwid('HWID');

// Call the '/setTags' Web Service
$response = $pushwoosh->setTags($request);

if($response->isOk()) {
    print 'Ok, operation successful.';
} else {
    print 'Oups, the operation failed :-('; 
    print 'Status code : ' . $response->getStatusCode();
    print 'Status message : ' . $response->getStatusMessage();
}

setBadge

/setBadge

POST https://api.pushwoosh.com/json/1.3/setBadge

Sends current badge value for a device to Pushwoosh. Called internally from the SDK.

Request Body

{
   "status_code":200,
   "status_message":"OK"
}
Example
  {
       "request":{
          "application" : "XXXXX-XXXXX", // required, Pushwoosh application code
          "hwid": "8f65b16df378e7a6bece9614e1530fb2", // required, hardware device ID used in /registerDevice function call  
          "badge": 4 // required, current badge on the application  
       }
    }

Called from the SDK internally. Sends current badge value for a device to Pushwoosh. This happens internally when app changes badge value on iOS device. Allows auto-incrementing badges to work properly.

This method IS NOT used to update the badge value on the device. Instead please use /createMessage request with the "ios_badges" parameter.

PHP
<?php
//see http://gomoob.github.io/php-pushwoosh/set-badge.html
use Gomoob\Pushwoosh\Model\Request\SetBadgeRequest;

// Creates the request instance
$request = RegisterDeviceRequest::create()
    ->setBadge(5)
    ->setHwid('HWID');

// Call the '/setBadge' Web Service
$response = $pushwoosh->setBadge($request);

if($response->isOk()) {
    print 'Ok, operation successful.';
} else {
    print 'Oups, the operation failed :-('; 
    print 'Status code : ' . $response->getStatusCode();
    print 'Status message : ' . $response->getStatusMessage();
}

applicationOpen

/applicationOpen

POST https://api.pushwoosh.com/json/1.3/applicationOpen

Registers an app open event. Called internally from the SDK.

Request Body

{
   "status_code":200,
   "status_message":"OK"
}
Example
  {
       "request":{
          "application" : "XXXXX-XXXXX", // required, Pushwoosh application code
          "hwid": "8f65b16df378e7a6bece9614e1530fb2" // required, hardware device ID used in /registerDevice function call    
       }
    }

pushStat

/pushStat

POST https://api.pushwoosh.com/json/1.3/pushStat

Registers a push open event. Called internally from the SDK.

Request Body

{
    "status_code": 200,
    "status_message": "OK",
    "response": null
}
Example
    {
       "request":{
          "application" : "XXXXX-XXXXX", // required, Pushwoosh application code
          "hwid": "8f65b16df378e7a6bece9614e1530fb2", // required, hardware device ID used in /registerDevice function call 
          "userId": "USER012345", // optional, the user id to associate with the push open event 
          "hash": "HASH_TAG" // optional, hash tag received in push notification (“p” parameter in the push payload) 
       }
    }
PHP
<?php
//see http://gomoob.github.io/php-pushwoosh/push-stat.html
use Gomoob\Pushwoosh\Model\Request\PushStatRequest;

// Creates the request instance
$request = PushStatRequest::create()
    ->setHash('hash')
    ->setHwid('HWID');

// Call the '/pushStat' Web Service
$response = $pushwoosh->pushStat($request);

if($response->isOk()) {
    print 'Ok, operation successful.';
} else {
    print 'Oups, the operation failed :-('; 
    print 'Status code : ' . $response->getStatusCode();
    print 'Status message : ' . $response->getStatusMessage();
}

messageDeliveryEvent

/messageDeliveryEvent

POST https://api.pushwoosh.com/json/1.3/messageDeliveryEvent

Registers push delivery event for the device. Called internally from the SDK.

Request Body

{
    "status_code": 200,
    "status_message": "OK",
    "response": null
}
Example
 {
       "request":{
          "application" : "XXXXX-XXXXX", // required, Pushwoosh application code
          "hwid": "8f65b16df378e7a6bece9614e1530fb2", // required, hardware device ID used in /registerDevice function call  
          "hash": "HASH_TAG" // optional, hash tag received in push notification (“p” parameter in the push payload) 
       }
 }

Last updated