Geozones API

getNearestZone

Вызывается внутри SDK. Получает параметры ближайшей Geozone и расстояние до нее. Также записывает местоположение устройства для геопушей.

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

Параметры тела запроса

Параметр	Тип	Обязательный	Описание
application	`string`	Да	Код приложения Pushwoosh
hwid	`string`	Да	Аппаратный ID устройства (HWID), используемый в запросе `/registerDevice`.
lat	`string`	Да	Широта устройства.
lng	`string`	Да	Долгота устройства.

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

{
  "request": {
    "application": "APPLICATION_CODE",
    "hwid": "HWID",
    "lat": 10.12345,
    "lng": 28.12345
  }
}

Пример на PHP

// See http://gomoob.github.io/php-pushwoosh/get-nearest-zone.html

use Gomoob\Pushwoosh\Model\Request\GetNearestZoneRequest;

// Creates the request instance
$request = GetNearestZoneRequest::create()
    ->setHwid('HWID')
    ->setLat(10.12345)
    ->setLng(28.12345);

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

if ($response->isOk()) {
    print 'Zone name : ' . $response->getResponse()->getName();
    print 'Latitude : ' . $response->getResponse()->getLat();
    print 'Longitude : ' . $response->getResponse()->getLng();
    print 'Range : ' . $response->getResponse()->getRange();
    print 'Distance : ' . $response->getResponse()->getDistance();
} else {
    print 'Oops, the operation failed :-(';
    print 'Status code : ' . $response->getStatusCode();
    print 'Status message : ' . $response->getStatusMessage();
}

addGeoZone

Добавляет Geozone в указанное приложение.

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

Параметры тела запроса

Параметр	Тип	Обязательный	Описание
auth	`string`	Да	Токен доступа к API из Панели управления Pushwoosh.
application	`string`	Да	Код приложения Pushwoosh
geozones	`array`	Да	Параметры Geozone в виде JSON-массива.
geozones.name	`string`	Да	Название Geozone.
geozones.lat	`string`	Обязателен для круга.	Широта Geozone. Опустите, если задан `polygon` — Geozone-полигон определяет свой центр самостоятельно.
geozones.lng	`string`	Обязателен для круга.	Долгота Geozone. Опустите, если задан `polygon` — Geozone-полигон определяет свой центр самостоятельно.
geozones.cooldown	`integer`	Да	Период тишины после отправки уведомления (в секундах).
geozones.range	`integer`	Обязателен для круга.	Радиус Geozone в метрах. Минимум 50. Опустите, если задан `polygon` — Geozone-полигон определяет свой радиус самостоятельно.
geozones.polygon	`object`	Нет	Делает Geozone полигоном вместо круга. Не может использоваться вместе с `lat`/`lng`/`range` — отправка обоих параметров будет отклонена. См. Geozones-полигоны.
geozones.content	`string or object`	Обязателен, если `presetCode` пуст.	Содержимое сообщения для Geozone.
geozones.presetCode	`string`	Обязателен, если `content` пуст.	Пресет пушей для использования вместо `content`.
geozones.cluster	`string`	Нет	Укажите `null`, чтобы отвязать кластер от Geozone.
geozones.campaign	`string`	Нет	Укажите `null`, чтобы отвязать кампанию от Geozone. Если параметр опущен, значение кампании останется без изменений. Примечание: имеет более высокий приоритет, чем кампания в пресете.
geozones.timetable	`object`	Нет	Устанавливает интервалы расписания.

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

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // Токен доступа к API из Панели управления Pushwoosh
    "application": "XXXXX-XXXXX",            // Код приложения Pushwoosh
    "geozones": [{
      "name": "Statue of George",            // обязательно. Название Geozone.
      "lat": "40.70087797",                   // обязательно. Широта Geozone.
      "lng": "-73.931851387",                 // обязательно. Долгота Geozone.
      "cooldown": 60,                         // в секундах, обязательно. Период тишины после отправки уведомления
      "range": 50,                            // в метрах, минимум 50, обязательно. Радиус Geozone.
      "content": "Lorem ipsum dolor sit amet,
       consectetur adipiscing elit.",         // или объект
      "presetCode": "AAAAA-BBBBB",            // опционально. Вместо контента можно использовать пресет пушей
      "cluster": "GEOZONE CLUSTER CODE",      // опционально. Будет применен период тишины кластера
      "campaign": "CAMPAIGN_CODE",            // опционально. Укажите null, чтобы отвязать кампанию от Geozone
      "timetable": {                          // опционально
        "timezone": 1234,                     // в секундах
        "Mon": [                              // доступные дни: Mon, Tue, Wed, Thu, Fri, Sat, Sun. Отправка пушей
          {
            "start": "04:11",
            "stop": "12:00"
          }
        ],
        "Sun": [
          {                                    // один или два интервала
            "start": "01:11",
            "stop": "17:00"
          },
          {
            "start": "18:01",
            "stop": "23:59"
          }
        ]
      }
    }]
  }
}

Добавление нескольких Geozones одновременно

geozones принимает массив, поэтому один вызов может создать целый пакет. Пакет проверяется целиком, прежде чем что-либо будет записано: если какая-либо запись отклонена, вызов завершается неудачно, и ни одна Geozone из этого запроса не создается. В ошибке указывается запись, вызвавшая проблему, по ее позиции в массиве, начиная с нуля:

{
  "status_code": 210,
  "status_message": "geozones[301]: range: range must be at least 50 meters"
}

Исправьте эту запись и отправьте запрос снова. В случае успеха GeoZones будет содержать новые числовые ID в том же порядке, в котором вы отправили записи.

Пакеты размером более 500 записей принимаются и разбиваются на части внутри системы. Весь массив по-прежнему проверяется перед первой записью, но сама запись не является атомарной для всех частей: запись может пройти проверку, но все равно не быть записанной, например, если указанный в ней пресет будет удален в промежутке. В этом случае вызов возвращает 200 с ID, которые были записаны, плюс массив Errors, в котором указана запись, остановившая выполнение, так что ничего созданного не теряется:

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "GeoZones": [100016750, 100016751],
    "Errors": [{ "index": 2, "message": "preset not found" }]
  }
}

Errors отсутствует, когда все записи были записаны, поэтому полностью успешный ответ не изменяется. Массив GeoZones, который короче отправленного вами массива, всегда означает, что некоторые записи не были созданы.

Geozones-полигоны

Отправьте polygon вместо lat/lng/range, чтобы сделать Geozone полигоном. polygon.vertices — это упорядоченное кольцо точек {lat, lng}, описывающее контур фигуры:

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",
    "application": "XXXXX-XXXXX",
    "geozones": [{
      "name": "Downtown mall — ground floor",
      "cooldown": 60,
      "polygon": {
        "vertices": [
          { "lat": 40.70087797, "lng": -73.931851387 },
          { "lat": 40.70112456, "lng": -73.931602211 },
          { "lat": 40.70095321, "lng": -73.930987654 },
          { "lat": 40.70068912, "lng": -73.931233456 }
        ]
      },
      "content": "Welcome! Enjoy 15% off your first purchase today."
    }]
  }
}

lat, lng и range выводятся из кольца — круг, который фактически отслеживает устройство, центрирован на фигуре с радиусом, достигающим ее самой дальней вершины (минимум 50 м). Отправка polygon вместе с lat/lng/range отклоняется.

Вы можете отправить кольцо открытым или закрытым — если последняя вершина повторяет первую, сервер удаляет этот замыкающий дубликат перед проверкой. Проверка вершин для полученного кольца: от 3 до 100 различных вершин. Кольцо также отклоняется, если его точки коллинеарны, если его ребра самопересекаются или если оно пересекает антимеридиан.

updateGeoZone

Обновляет свойства Geozone.

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

Параметры тела запроса

Параметр	Тип	Обязательный	Описание
auth	`string`	Да	Токен доступа к API из Панели управления Pushwoosh.
geoZoneId	`string`	Да	ID Geozone из запроса `/addGeoZone`.
name	`string`	Нет	Новое название Geozone.
cooldown	`integer`	Нет	Период тишины для обновления, в секундах.
status	`integer`	Нет	0 - деактивирована, 1 - активирована.
content	`string`	Нет	Контент для пуш-уведомления Geozone. Не может использоваться вместе с `presetCode`.
cluster	`string`	Нет	Новое название кластера. Укажите `null`, чтобы отвязать кластер от Geozone.
campaign	`string`	Нет	Новый ID кампании. Укажите `null`, чтобы отвязать кампанию от Geozone. Если параметр опущен, значение кампании не изменится. Имеет более высокий приоритет, чем кампания из пресета.
lat	`number`	Нет	Широта Geozone. Не может использоваться вместе с `polygon`.
lng	`number`	Нет	Долгота Geozone. Не может использоваться вместе с `polygon`.
range	`integer`	Нет	Новый радиус в метрах. Не может использоваться вместе с `polygon`.
polygon	`object`	Нет	Новое кольцо вершин `{lat, lng}` — заменяет фигуру и заново вычисляет `lat`/`lng`/`range` из нее. См. Geozones-полигоны. Работает в обе стороны: отправьте его для существующей круглой Geozone, чтобы превратить ее в полигон, или отправьте пустое кольцо (`{"vertices": []}`) для существующей Geozone-полигона, чтобы превратить ее обратно в круг. Полностью опустите `polygon`, чтобы оставить фигуру без изменений. Валидация вершин такая же, как в `addGeoZone`.
timetable	`object`	Нет	Расписание Geozone. См. дополнительную информацию ниже.

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

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // обязательно, токен доступа к API из Панели управления Pushwoosh
    "geoZoneId": 100016750,                  // обязательно, из метода /addGeoZone
    "name": "new geozone name",              // опционально
    "cooldown": 222,                         // в секундах, опционально
    "status": 0,                             // опционально, 0 - деактивирована, 1 - активирована
    "presetCode": "BBBBB-AAAAA",             // опционально, не может использоваться вместе с "content"
    "content": "new geozone content",        // опционально, не может использоваться вместе с "presetCode"
    "cluster": "GEOZONE CLUSTER CODE",       // опционально. Укажите null, чтобы отвязать кластер от Geozone
    "campaign": "CAMPAIGN_CODE",             // опционально. Укажите null, чтобы отвязать кампанию от Geozone
    "lat": 10.56,                            // опционально, широта Geozone
    "lng": 12.523,                           // опционально, долгота Geozone
    "range": 500,                            // опционально, радиус Geozone
    "timetable": {                           // опционально
      "timezone": 1234,                      // в секундах
      "Mon": [                               // доступные дни: Mon, Tue, Wed, Thu, Fri, Sat, Sun. Отправка пушей
        {
          "start": "04:11",
          "stop": "12:00"
        }
      ],
      "Sun": [
        {                                    // один или два интервала
          "start": "01:11",
          "stop": "17:00"
        },
        {
          "start": "18:01",
          "stop": "23:59"
        }
      ]
    }
  }
}

deleteGeoZone

Удаляет Geozones из приложения.

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

Параметры тела запроса

Параметр	Тип	Обязательный	Описание
auth	`string`	Да	Токен доступа к API из Панели управления Pushwoosh.
application	`string`	Да	Код приложения Pushwoosh
geozones	`string`	Да	Массив ID или один ID Geozone для удаления.

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

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // обязательно, токен доступа к API из Панели управления Pushwoosh
    "application": "XXXXX-XXXXX",            // обязательно, код приложения Pushwoosh
    "geozones": [550, 526]                   // обязательно, ID Geozones
  }
}

addGeoZoneCluster

Добавляет кластер Geozone в приложение.

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

Параметры тела запроса

Параметр	Тип	Обязательный	Описание
auth	`string`	Да	Токен доступа к API из Панели управления Pushwoosh.
application	`string`	Да	Код приложения Pushwoosh
name	`string`	Да	Название кластера.
cooldown	`integer`	Да	Задержка перед тем, как один пользователь сможет получить то же сообщение от кластера Geozone, в секундах.

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

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // обязательно, токен доступа к API из Панели управления Pushwoosh
    "application": "XXXXX-XXXXX",            // обязательно, код приложения Pushwoosh
    "name": "Raccoon city",                  // обязательно, название кластера
    "cooldown": 3210                         // обязательно, в секундах
  }
}

deleteGeoZoneCluster

Удаляет кластер Geozone из приложения.

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

Параметры тела запроса

Параметр	Тип	Обязательный	Описание
auth	`string`	Да	Токен доступа к API из Панели управления Pushwoosh.
application	`string`	Да	Код приложения Pushwoosh
geoZoneCluster	`string`	Да	ID кластера Geozone для удаления.

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

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // обязательно, токен доступа к API из Панели управления Pushwoosh
    "application": "XXXXX-XXXXX",            // обязательно, код приложения Pushwoosh
    "geoZoneCluster": "EA1CE-69405"          // обязательно, ID кластера, полученный из запроса /addGeoZoneCluster
  }
}

listGeoZones

Получает список Geozones для приложения.

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

Параметры тела запроса

Параметр	Тип	Обязательный	Описание
auth	`string`	Да	Токен доступа к API из Панели управления Pushwoosh.
application	`string`	Да	Код приложения Pushwoosh

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

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // обязательно, токен доступа к API из Панели управления Pushwoosh
    "application": "XXXXX-XXXXX"             // обязательно, код приложения Pushwoosh
  }
}

listGeoZoneClusters

Получает список кластеров Geozone для приложения.

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

Параметры тела запроса

Параметр	Тип	Обязательный	Описание
auth	`string`	Да	Токен доступа к API из Панели управления Pushwoosh.
application	`string`	Да	Код приложения Pushwoosh

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

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // обязательно, токен доступа к API из Панели управления Pushwoosh
    "application": "XXXXX-XXXXX"             // обязательно, код приложения Pushwoosh
  }
}