Device API

registerDevice

POST https://api.wavesend.ru/json/1.3/registerDevice

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

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

Имя	Обязательно	Значение	Описание
Authorization	Да	Token XXXX	API Device Token для доступа к Device API. Замените XXXX вашим настоящим API Device Token.

Тело запроса

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

200

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

Пример

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

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

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

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

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

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

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

{
  "request": {
    "application": "XXXXX-XXXXX",        // обязательно. Код Application Wavesend
    "hwid": "whatsapp:+0000000000",      // обязательно. Префикс WhatsApp и действительный номер телефона
    "timezone": 3600,                    // необязательно. Смещение времени в секундах
    "device_type": 21,                   // обязательно. Тип устройства WhatsApp — 21
    "language": "en",                    // необязательно. Код языка по ISO 639-1|639-2
    "userId": "Alex",                    // необязательно. Идентификатор пользователя
    "tags": {                            // необязательно. Значения Tag для пользовательской сегментации
      "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). Номер телефона должен быть действительным, Wavesend проверит его.

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

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

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

{
   "request": {
      "application": "XXXXX-XXXXX",           // обязательно. Код Application Wavesend
      "hwid": "+0000000000",                  // обязательно. Действительный номер телефона в формате E.164
      "timezone": 3600,                       // необязательно. Смещение времени в секундах
      "device_type": 18,                      // обязательно. Тип устройства SMS — 18
      "language": "en",                       // необязательно. Код языка по ISO 639-1|639-2
      "userId": "Alex",                       // необязательно. Идентификатор пользователя
      "tags": {                               // необязательно. Значения Tag для пользовательской сегментации
           "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://go.wavesend.ru/json/1.3/unregisterDevice

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

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

Имя	Обязательно	Значение	Описание
Authorization	Да	Token XXXX	API Device Token для доступа к Device API. Замените XXXX вашим настоящим API Device Token.

Тело запроса

Имя	Тип	Описание
application*	string	Код Application Wavesend
hwid*	string	Hardware device ID, используемый в запросе /registerDevice.

200

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

Пример

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

Note

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

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

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

setTags

POST https://go.wavesend.ru/json/1.3/setTags

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

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

Имя	Обязательно	Значение	Описание
Authorization	Да	Token XXXX	API Device Token для доступа к Device API. Замените XXXX вашим настоящим API Device Token.

Тело запроса

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

200

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

Note

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

Пример

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

Инкремент значений тега типа Integer

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

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

Декремент значений тега типа Integer

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

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

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

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

Пример

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

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

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

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

Установка тегов по User ID

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

Caution

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

Пример

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

Note

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

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

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

getTags

POST https://go.wavesend.ru/json/1.3/getTags

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

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

Имя	Обязательно	Значение	Описание
Authorization	Да	Token XXXX	API Device Token для доступа к Device API. Замените XXXX вашим настоящим API Device Token.

Тело запроса

Имя	Тип	Описание
application*	string	Код Application Wavesend
userId	string	User ID для использования вместо hwid. Если используется вместе с hwid, то hwid имеет приоритет.
hwid	string	Hardware device ID, используемый в запросе /registerDevice.

200

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

Пример

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

setBadge

POST https://api.wavesend.ru/json/1.3/setBadge

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

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

Имя	Обязательно	Значение	Описание
Authorization	Да	Token XXXX	API Device Token для доступа к Device API. Замените XXXX вашим настоящим API Device Token.

Тело запроса

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

200

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

Пример

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

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

Caution

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

applicationOpen

POST https://api.wavesend.ru/json/1.3/applicationOpen

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

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

Имя	Обязательно	Значение	Описание
Authorization	Да	Token XXXX	API Device Token для доступа к Device API. Замените XXXX вашим настоящим API Device Token.

Тело запроса

Имя	Тип	Описание
application*	string	Код Application Wavesend
hwid*	string	Hardware device ID, используемый в запросе /registerDevice.

200

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

Пример

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

pushStat

POST https://api.wavesend.ru/json/1.3/pushStat

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

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

Имя	Обязательно	Значение	Описание
Authorization	Да	Token XXXX	API Device Token для доступа к Device API. Замените XXXX вашим настоящим API Device Token.

Тело запроса

Имя	Тип	Описание
application*	string	Код Application Wavesend
hwid*	string	Hardware device 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",               // обязательно. Код Application Wavesend
    "hwid": "8f65b16dfXXXX7a6beXXXX14e1530fb2", // обязательно. Hardware device ID, используемый в /registerDevice API
    "userId": "USER012345",                     // необязательно. User ID для связи с событием открытия push-уведомления
    "hash": "HASH_TAG"                          // необязательно. Хеш-тег, полученный в push-уведомлении
                                                //           (параметр "p" в полезной нагрузке Push)
  }
}

messageDeliveryEvent

POST https://api.wavesend.ru/json/1.3/messageDeliveryEvent

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

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

Имя	Обязательно	Значение	Описание
Authorization	Да	Token XXXX	API Device Token для доступа к Device API. Замените XXXX вашим настоящим API Device Token.

Тело запроса

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

200

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

Пример

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