Device API

registerDevice

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

Вызывается SDK изнутри. Регистрирует устройство для приложения.

Заголовки запроса

Имя	Обязательный	Значение	Описание
Authorization	Да	Token XXXX	Токен API устройства (Device API Token) для доступа к Device API. Замените XXXX на ваш фактический токен Device API.

Тело запроса

Имя	Тип	Описание
application*	string	Код приложения Pushwoosh
push_token	string	Push-токен для устройства.
language	string	Языковая локаль устройства. Должен быть двухбуквенный код в нижнем регистре в соответствии со стандартом ISO-639-1.
hwid*	string	Уникальная строка для идентификации устройства (IDFV на iOS, случайно сгенерированное значение на Android). Узнать больше
timezone	integer	Смещение часового пояса в секундах для устройства.
device_type*	integer	Тип устройства. Возможные значения см. ниже.
email	string	Адрес электронной почты для регистрации (используйте для email-пользователей вместо HWID и push-токена).
tags	object	Значения тегов для присвоения зарегистрированному устройству.

200

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

Пример

{
  "request": {
    "application": "XXXXX-XXXXX",        // обязательно. Код приложения Pushwoosh
    "push_token": "dec301908b9ba8XXXXX57a58e40f96f5XXXXX2068674f5XXXXa25cdc250a2a41", // необязательно.
    "hwid": "1CA6XXXXX-8DAC-XXXXX-XXXXX-B756288B6D3C",                                   // обязательно. Аппаратный ID устройства
    "idfa": "AEBE52E7-0XXXXX-455A-XXXXX-E57283966239",                                   // необязательно.
    "timezone": 3600,                    // необязательно. Смещение в секундах
    "device_type": 1,                    // обязательно. Возможные значения см. ниже. Для email
                                         //           используйте параметры "emails", как описано ниже.
    "email": "email_address@domain.com", // используйте вместо "hwid" и "push_token" для регистрации
                                         //           адреса электронной почты для вашего email-проекта
    "language": "en",                    // необязательно. Код языка ISO 639-1|639-2
    "userId": "Alex",                    // необязательно.
    "tags": {                            // необязательно. Значения тегов для установки на зарегистрированное устройство
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"], // устанавливает список значений для тегов типа List
      "DateTag": "2024-10-02 22:11",     // обратите внимание, что время должно быть в UTC
      "BooleanTag": true                 // допустимые значения: true, false
    },

    // системные теги, необязательные
    "app_version": "1.2.3",
    "device_model": "Samsung SM-G355H",
    "os_version": "2.3",

    // необязательные ключи шифрования для chrome/firefox
    "public_key": "BNmDO4BTKEMJqaqprTf7t/HBXXXXX/orcXXXXX/scS5CFP6XXXXXHI1/GgRQD8c4kTxTEEF0quvIUiLQqoBY0/Qo=",
    "auth_token": "RlRmCXXXXX/s7XXXXXjKFzoQ==",

    // необязательные ключи FCM для Chrome (для XMPP)
    "fcm_token": "BNmDO4BTKEMJXXXXXprTf7t/XXXXXBQ/orXXXXXc/scS5CFP6zhQGIHI1/GgRQD8c4kTxTEEF0quvIUiLQqoBY0/Qo=",
    "fcm_push_set": "RlXXXXXGM/s7XXXXXjKFzoQ=="
  }
}

Возможные типы устройств:

• 1 – iOS
• 3 – Android
• 7 – Mac OS X
• 8 – Windows
• 9 – Amazon
• 10 – Safari
• 11 – Chrome
• 12 – Firefox
• 14 – Email
• 17 – Huawei
• 18 – SMS
• 21 – WhatsApp

Регистрация email-устройств

Чтобы зарегистрировать email-подписчика для вашего приложения, отправьте параметр "email": "email_address@domain.com" в вашем запросе /registerDevice или /registerEmail следующим образом:

Пример запроса

{
  "request":{
    "application": "XXXXX-XXXXX",        // обязательно. Код приложения Pushwoosh
    "email": "email_address@domain.com", // обязательно. Адрес электронной почты для регистрации в вашем email-проекте
    "language": "en",                    // необязательно. Код языка ISO 639-1|639-2
    "userId": "Alex",                    // необязательно.
    "tags": {                            // необязательно. Значения тегов для установки на зарегистрированное устройство
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"], // устанавливает список значений для тегов типа List
      "DateTag": "2024-10-02 22:11",     // обратите внимание, что время должно быть в UTC
      "BooleanTag": true                 // допустимые значения: true, false
    }
  }
}

Регистрация устройств WhatsApp

Чтобы зарегистрировать устройство WhatsApp для вашего приложения, следуйте этим рекомендациям:

• hwid: Убедитесь, что это поле содержит префикс whatsapp:, за которым следует номер телефона в формате E.164 (например, whatsapp:+0000000000). Номер телефона должен быть действительным, что будет проверено Pushwoosh.

• Push token: Push-токен не требуется, так как hwid автоматически будет функционировать как push-токен.

• device_type: Установите это поле в 21, чтобы указать WhatsApp в качестве платформы.

Пример запроса

{
  "request": {
    "application": "XXXXX-XXXXX",        // обязательно. Код приложения Pushwoosh
    "hwid": "whatsapp:+0000000000",      // обязательно. Префикс WhatsApp и действительный номер телефона
    "timezone": 3600,                    // необязательно. Смещение времени в секундах
    "device_type": 21,                   // обязательно. Тип устройства WhatsApp — 21
    "language": "en",                    // необязательно. Код языка ISO 639-1|639-2
    "userId": "Alex",                    // необязательно. Идентификатор пользователя
    "tags": {                            // необязательно. Значения тегов для пользовательской сегментации
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"],
      "DateTag": "2024-10-02 22:11",     // формат UTC
      "BooleanTag": true
    },
    "app_version": "1.2.3",              // необязательно. Версия приложения
    "device_model": "Samsung SM-G355H",  // необязательно. Модель устройства
    "os_version": "2.3"                  // необязательно. Версия операционной системы
  }
}

Регистрация SMS-устройств

Чтобы зарегистрировать SMS-устройство для вашего приложения, следуйте этим рекомендациям:

• hwid: Убедитесь, что это поле содержит номер телефона в формате E.164 (например, +0000000000). Номер телефона должен быть действительным, что будет проверено Pushwoosh.

• Push token: Push-токен не требуется, так как hwid автоматически будет функционировать как push-токен.

• device_type: Установите это обязательное поле в 18, чтобы указать SMS в качестве платформы.

Пример запроса

{
   "request": {
      "application": "XXXXX-XXXXX",           // обязательно. Код приложения Pushwoosh
      "hwid": "+0000000000",                  // обязательно. Действительный номер телефона в формате E.164
      "timezone": 3600,                       // необязательно. Смещение времени в секундах
      "device_type": 18,                      // обязательно. Тип SMS-устройства — 18
      "language": "en",                       // необязательно. Код языка ISO 639-1|639-2
      "userId": "Alex",                       // необязательно. Идентификатор пользователя
      "tags": {                               // необязательно. Значения тегов для пользовательской сегментации
           "StringTag": "string value",
           "IntegerTag": 42,
           "ListTag": ["string1", "string2"],
           "DateTag": "2024-10-02 22:11",     // формат UTC
           "BooleanTag": true
      },
      "app_version": "1.2.3",                 // необязательно. Версия приложения
      "device_model": "Samsung SM-G355H",     // необязательно. Модель устройства
      "os_version": "2.3"                     // необязательно. Версия операционной системы
   }
}

Коды состояния:

Код состояния HTTP	status_code	Описание
200	200	Устройство успешно зарегистрировано
200	210	Ошибка аргумента. См. status_message для получения дополнительной информации.
400	N/A	Неверно сформированная строка запроса
500	500	Внутренняя ошибка

unregisterDevice

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

Удаляет push-токен устройства. Отмененное устройство по-прежнему учитывается в общем количестве устройств (Total Devices) и может быть доступно для In-App сообщений. Вызывается SDK изнутри.

Заголовки запроса

Имя	Обязательный	Значение	Описание
Authorization	Да	Token XXXX	Токен API устройства (Device API Token) для доступа к Device API. Замените XXXX на ваш фактический токен Device API.

Тело запроса

Имя	Тип	Описание
application*	string	Код приложения Pushwoosh
hwid*	string	Аппаратный ID устройства, используемый в запросе /registerDevice.

200

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

Пример

{
  "request": {
    "application": "XXXXX-XXXXX",              // обязательно. Код приложения Pushwoosh
    "hwid": "8f65b16XXXXXe7a6beceXXXXX530fb2"  // обязательно. Аппаратный ID устройства, используемый в API /registerDevice
  }
}

Примечание

Для email вызовите /deleteEmail.

Коды состояния:

Код состояния HTTP	status_code	Описание
200	200	Устройство успешно отписано
200	210	Ошибка аргумента. См. status_message для получения дополнительной информации.
400	N/A	Неверно сформированная строка запроса
500	500	Внутренняя ошибка

setTags

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

Устанавливает значения тегов для устройства. Вызывается из SDK.

Заголовки запроса

Имя	Обязательный	Значение	Описание
Authorization	Да	Token XXXX	Токен API устройства (Device API Token) для доступа к Device API. Замените XXXX на ваш фактический токен Device API.

Тело запроса

Имя	Тип	Описание
application*	string	Код приложения Pushwoosh
hwid*	string	Аппаратный ID устройства, используемый в запросе /registerDevice.
tags*	object	JSON-объект устанавливаемых тегов, отправьте “null” для удаления значения.

200

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

Примечание

Метод вызывается из SDK. Его можно вызывать удаленно с вашего бэкенда, однако вам необходимо поддерживать актуальную базу данных hwid на стороне бэкенда.

Пример

{
  "request":{
    "application": "XXXXX-XXXXX",               // обязательно. Код приложения Pushwoosh
    "hwid": "8f65b16XXXXXe7a6becXXXXXe1530fb2", // обязательно. Аппаратный ID устройства, используемый в API /registerDevice
    "tags": {                                   // обязательно.
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"],        // устанавливает список значений для тегов типа List
      "DateTag": "2024-10-02 22:11",            // обратите внимание, что время указано в UTC
      "BooleanTag": true                        // допустимые значения: true, false
    }
  }
}

Увеличение значений целочисленных тегов

Чтобы увеличить значение целочисленного тега (Integer Tag), используйте параметр operation со значением “increment” следующим образом:

{
  "request":{
    "application": "12345-67890",                   // обязательно. Код приложения Pushwoosh
    "hwid": "21AB7628-XXXX-XXXX-CCC0-PO287CS24CA4", // обязательно. Аппаратный ID устройства, используемый в API /registerDevice
    "tags": {                                       // обязательно.
      "Level": {                                    // Имя тега
        "operation": "increment",                   // перезаписывает целочисленный тег с шагом следующего значения
        "value": 1                                  // инкремент для значения тега
      }
    }
  }
}

Уменьшение значений целочисленных тегов

Для уменьшения используйте отрицательные числа в качестве значения для операции “increment” (-1, -2, -3, -n):

{
  "request":{
    "application": "12345-67890",                   // обязательно. Код приложения Pushwoosh
    "hwid": "21AB7628-XXXX-XXXX-CCC0-PO287CS24CA4", // обязательно. Аппаратный ID устройства, используемый в API /registerDevice
    "tags": {                                       // обязательно
      "Level": {                                    // Имя тега
        "operation": "increment",                   // перезаписывает целочисленный тег с декрементом следующего значения
        "value": -1                                 // декремент для значения тега
      }
    }
  }
}

Добавление значений в теги типа List

Чтобы расширить тег типа List новыми значениями, используйте параметр operation со значением “append” следующим образом:

Пример

{
  "request": {
    "hwid": "3d124a79XXXXf189XXXX7dfd9XXXXafd", // обязательно. Аппаратный ID устройства, используемый в API /registerDevice
    "application": "6XXXX-XXXX3",               // обязательно. Код приложения Pushwoosh
    "tags": {                                   // обязательно.
      "ListTag": {                              // Имя тега
        "operation": "append",                  // добавляет следующие значения в список значений тега
        "value": [                              // значения для добавления
          "tag2",
          "tag3"
        ]
      }
    }
  }
}

Удаление значений из тегов типа List

Чтобы удалить некоторые значения из тега типа List, используйте операцию “remove” следующим образом:

{
  "request":{
    "application": "12345-67890",                   // обязательно. Код приложения Pushwoosh
    "hwid": "21AB7628-XXXX-XXXX-CCC0-PO287CS24CA4", // обязательно. Аппаратный ID устройства, используемый в API /registerDevice
    "tags": {                                       // обязательно.
      "In-App Product": {                           // Имя тега
        "operation": "remove",                      // удаляет следующие значения из тега типа List
        "value": "outwear_02"                       // значение или значения для удаления
      }
    }
  }
}

Установка тегов по UserID

Чтобы установить теги для всех устройств, связанных с определенным User ID, используйте параметр “userId” вместо “hwid”.

Осторожно

Убедитесь, что тег, для которого вы устанавливаете значения, является специфичным для пользователя (user-specific).

Пример

{
  "request":{
    "application": "AAAAA-BBBBB", // Код приложения Pushwoosh
    "userId": "some_user",        // User ID, для которого вы хотите установить теги
    "tags": {                     // теги и значения для установки
      "Language": "es"
    }
  }
}

Примечание

Для email вызовите /setEmailTags.

Коды состояния:

Код состояния HTTP	status_code	Описание
200	200	Теги были успешно установлены
200	210	Ошибка аргумента. См. status_message для получения дополнительной информации.
400	N/A	Неверно сформированная строка запроса
500	500	Внутренняя ошибка

getTags

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

Получает список тегов с соответствующими значениями для конкретного устройства.

Заголовки запроса

Имя	Обязательный	Значение	Описание
Authorization	Да	Token XXXX	Токен API устройства (Device API Token) для доступа к Device API. Замените XXXX на ваш фактический токен Device API.

Тело запроса

Имя	Тип	Описание
application*	string	Код приложения Pushwoosh
userId	string	User ID для использования вместо “hwid”. Если используется вместе с “hwid”, “hwid” имеет приоритет.
hwid	string	Аппаратный ID устройства, используемый в запросе /registerDevice.

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "result": {
      "Language": "fr"
    }
  }
}

Пример

{
  "request":{
    "application": "XXXXX-XXXXX",   // обязательно. Код приложения Pushwoosh
    "hwid": "HWID",                 // необязательно. Аппаратный ID устройства, используемый в API /registerDevice
    "userId": "USER_ID"             // необязательно. Может использоваться вместо "hwid" для получения тегов для конкретного пользователя
  }
}

setBadge

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

Отправляет текущее значение значка (badge) для устройства в Pushwoosh. Вызывается SDK изнутри.

Заголовки запроса

Имя	Обязательный	Значение	Описание
Authorization	Да	Token XXXX	Токен API устройства (Device API Token) для доступа к Device API. Замените XXXX на ваш фактический токен Device API.

Тело запроса

Имя	Тип	Описание
application*	string	Код приложения Pushwoosh
hwid*	string	Аппаратный ID устройства, используемый в запросе /registerDevice.
badge*	integer	Текущий значок в приложении.

200

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

Пример

{
  "request":{
    "application": "XXXXX-XXXXX",               // обязательно. Код приложения Pushwoosh
    "hwid": "8f65b16dXXXXe7a6XXXX9614XXXX0fb2", // обязательно. Аппаратный ID устройства, используемый в API /registerDevice
    "badge": 4                                  // обязательно. Текущий значок в приложении
  }
}

Вызывается из SDK изнутри. Отправляет текущее значение значка для устройства в Pushwoosh. Это происходит внутри, когда приложение изменяет значение значка на устройстве iOS. Позволяет правильно работать автоинкрементируемым значкам.

Осторожно

Этот метод НЕ используется для обновления значения значка на устройстве. Вместо этого используйте запрос /createMessage с параметром "ios_badges".

applicationOpen

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

Регистрирует событие открытия приложения. Вызывается SDK изнутри.

Заголовки запроса

Имя	Обязательный	Значение	Описание
Authorization	Да	Token XXXX	Токен API устройства (Device API Token) для доступа к Device API. Замените XXXX на ваш фактический токен Device API.

Тело запроса

Имя	Тип	Описание
application*	string	Код приложения Pushwoosh
hwid*	string	Аппаратный ID устройства, используемый в запросе /registerDevice.

200

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

Пример

{
  "request": {
    "application": "XXXXX-XXXXX",              // обязательно. Код приложения Pushwoosh
    "hwid": "8f65b16dXXXXe7a6XXXX9614eXXXXfb2" // обязательно. Аппаратный ID устройства, используемый в API /registerDevice
  }
}

pushStat

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

Регистрирует событие открытия push-уведомления. Вызывается SDK изнутри.

Заголовки запроса

Имя	Обязательный	Значение	Описание
Authorization	Да	Token XXXX	Токен API устройства (Device API Token) для доступа к Device API. Замените XXXX на ваш фактический токен Device API.

Тело запроса

Имя	Тип	Описание
application*	string	Код приложения Pushwoosh
hwid*	string	Аппаратный ID устройства, используемый в запросе /registerDevice.
userId	string	User ID для связи с событием открытия push-уведомления.
hash	string	Хэш-тег, полученный в push-уведомлении (параметр “p” в полезной нагрузке push-уведомления).

200

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

Пример

{
  "request": {
    "application": "XXXXX-XXXXX",               // обязательно. Код приложения Pushwoosh
    "hwid": "8f65b16dfXXXX7a6beXXXX14e1530fb2", // обязательно. Аппаратный ID устройства, используемый в API /registerDevice
    "userId": "USER012345",                     // необязательно. User ID для связи с событием открытия push-уведомления
    "hash": "HASH_TAG"                          // необязательно. Хэш-тег, полученный в push-уведомлении
                                                //           (параметр "p" в полезной нагрузке push-уведомления)
  }
}

messageDeliveryEvent

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

Регистрирует событие доставки push-уведомления для устройства. Вызывается SDK изнутри.

Заголовки запроса

Имя	Обязательный	Значение	Описание
Authorization	Да	Token XXXX	Токен API устройства (Device API Token) для доступа к Device API. Замените XXXX на ваш фактический токен Device API.

Тело запроса

Имя	Тип	Описание
application*	string	Код приложения Pushwoosh
hwid*	string	Аппаратный ID устройства, используемый в запросе /registerDevice.
hash	string	Хэш-тег, полученный в push-уведомлении (параметр “p” в полезной нагрузке push-уведомления).

200

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

Пример

 {
  "request": {
    "application": "XXXXX-XXXXX",               // обязательно. Код приложения Pushwoosh
    "hwid": "8f65b16dfXXXX7a6bece9XXXX1530fb2", // обязательно. Аппаратный ID устройства, используемый в API /registerDevice
    "hash": "HASH_TAG"                          // необязательно. Хэш-тег, полученный в push-уведомлении
                                                //           (параметр "p" в полезной нагрузке push-уведомления)
  }
}