Сценарии использования

Создание группы

Для отправки сообщения необходимо указать уникальное имя группы. Каждая отправка обязательно принадлежит какой-либо созданной группе. Это позволяет объединять отправки в отчете.

Для создания группы выполните запрос POST /push/v1/management/groups:

curl -X POST \
  'https://push.api.appmetrica.yandex.net/push/v1/management/groups' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: OAuth 05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037' \
  -d '{"group":{"app_id":XXXXXX,"name":"the_name_of_the_group"}}'

В случае успешного запроса будет получен ответ вида:

{
  "group": {
    "id": XXXXXX,
    "app_id": XXXXXX,
    "name": "the_name_of_the_group"
  }
}

Полученный group_id необходимо использовать для дальнейших отправок push-сообщений.

Отправка push-сообщения

Для отправки сообщения необходимо указать идентификатор группы и тег отправки. Несколько отправок могут иметь одинаковый тег. Тег может быть произвольной строкой, отображается в отчетах на втором уровне.

Для отправки сообщения выполните запрос POST /push/v1/send-batch:

curl -X POST \
  'https://push.api.appmetrica.yandex.net/push/v1/send-batch' \
  -H 'Authorization: OAuth 05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037' \
  -H 'Content-Type: application/json' \
  -d '{
  "push_batch_request": {
    "group_id": XXXXXX,
      "tag": "some_tag",
      "batch": [
      {
        "messages": {
          "android": {
            "silent": false,
            "content": {
              "title": "Sample android title",
              "text": "Sample android text",
              "icon": "46",
              "icon_background": "#FFFFFFFF",
              "banner": "http://example.png",
              "data": "foobarbaz",
              "priority": -2,
              "collapse_key": 2001,
              "vibration": [0, 500],
              "led_color": "#FFFFFF",
              "led_interval": 50,
              "led_pause_interval": 50,
              "time_to_live": 180
            }
          },
          "iOS": {
            "silent": false,
            "content": {
              "text": "Sample iOS text",
              "badge": "0",
              "data": "foobarbaz",
              "sound": "disable"
            }
          }
        },
        "devices": [
          {
            "id_type": "ios_ifa",
            "id_values": ["8003C3CF-A3BC-4DDD-B6DF-1DD......"]
          },
          {
            "id_type": "google_aid",
            "id_values": ["8e4dd44b-82ec-43d0-a5de-321......"]
          }
        ]
      }
    ]
  }'
Примечание. Описание полей запроса приведены в разделе Отправка push-сообщений.

В случае успешного запроса будет получен ответ вида:

{
  "push_response": {
  "transfer_id": XXXXXX
  }
}

Полученный transfer_id используется для проверки статуса отправки.

Проверка статуса отправки

Для проверки статуса отправки используется идентификатор отправки transferId.
Примечание. Вы также можете отслеживать отправку по заданному значению поля client_transfer_id. Подробнее в разделе Отправка push-сообщений.

Для отправки сообщения выполните запрос GET /push/v1/status/{transferId}:

curl -X GET \
  'https://push.api.appmetrica.yandex.net/push/v1/status/XXXXXX' \
  -H 'Authorization: OAuth 05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037'

В случае успешного запроса будет получен ответ вида:

{
  "transfer": {
    "creation_date": "2017-11-03T18:29:25+03:00",
    "id": XXXXXX,
    "status": "failed",
    "tag": "some_tag",
    "group_id": XXXXXX,
    "errors": [
      "Invalid push credentials for platform android"
    ]
  }
}
Примечание. Описание полей ответа приведены в разделе Проверка статуса отправки по transferId.

Получение отчета по push-кампании

Для получения отчета по отправленным push-сообщениям необходимо использовать API отчетов.

Для получения информации по отправке push-сообщений используйте запрос следующего типа

curl -X GET \
  'https://api.appmetrica.yandex.ru/stat/v1/data?limit=10&date1=today&date2=today&ids=XXXXXX&metrics=ym:pc:users&dimensions=ym:pc:group,ym:pc:tag,ym:pc:transfer'
  -H 'Authorization: OAuth 05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037'

В случае успешного запроса будет получен ответ вида:

{
  "dimensions": [
    {
      "id": "1",
      "name": "the_name_of_the_group"
    },
    {
      "name": "some_tag"
    },
    {
      "name": "99"
    }
  ],
  "metrics": [
      1
  ]
}
...