Use cases

Creating a group

To send a push message you should define the unique name of the group. Each sending is owned by any created group. It allows you to group message sendings in the report.

To create a group make the following request 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"}}'

If the request is successful, you will receive a response that looks like:

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

The received group_id must be used for further push messages sending.

Sending a push message

To send a push you should specify the group ID and a dispatch tag. Multiple dispatches can have the same tag. The tag is an arbitrary string displayed in reports at the second level.

To send a push message, make the following request 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......"]
          }
        ]
      }
    ]
  }'
Note. The description of the request fields is given in the section Sending push messages.

If the request is successful, you will receive a response that looks like:

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

The recieved transfer_id is used to check the status of sending.

Checking the status of sending

To check the status of sending use the transferId dispatch identifier.
Note. You can also check the status by using the specified value of the client_transfer_id field. For more information, see Sending push messages.

To check the status make the following request GET /push/v1/status/{transferId}:

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

If the request is successful, you will receive a response that looks like:

{
  "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"
    ]
  }
}
Note. The description of the response fields is given in the section Checking the status of sending with transferId.

Getting a push campaign report

To get a push campaign report, use the Reporting API.

To get the information about sending use the following request

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'

If the request is successful, you will receive a response that looks like:

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