Мобильные приложения: HTTP API

Android. JSON API: сессия, выдача, действия, просмотр.

Kotlin SDK · Создать площадку

Авторизация

API-ключ только на сервере. Запросы с Origin отклоняются. Серверный ключ должен принадлежать владельцу площадки. Необходимо передавать один и тот же ID в ads, interact и seen.

POST /api/v1/mobile/session

POST /api/v1/mobile/session
Content-Type: application/json

{
  "platform_id": "plt_example",
  "installation_id": "installation-123456789",
  "os": "android",
  "app_identifier": "com.example.chat"
}

Ответ: access_token, expires_at. Срок сессии 1 час. installation_id: случайный постоянный ID установки, 16-128 символов. Package передаётся клиентом; это не аттестация приложения.

Сервер: stable_user_id и user_id равнозначны, 1-128 символов; не совмещаются с installation_id. Допустимые символы ID: A-Z a-z 0-9 _ . : -. os и app_identifier обязательны при ограничении по package; os только android.

POST /api/v1/mobile/ads

POST /api/v1/mobile/ads
Authorization: Bearer sk_live_EXAMPLE
Content-Type: application/json

{
  "platform_id": "plt_example",
  "stable_user_id": "customer_42",
  "os": "android",
  "app_identifier": "com.example.chat",
  "placement": "chat",
  "language_code": "ru",
  "context": {"question": "Headphones?", "answer": "Some options"},
  "test": true,
  "test_format": "card"
}

Test возвращает демонстрационную рекламу без списаний и начислений.

Ответ

{
  "has_ad": true,
  "ad": {
    "delivery_id": "imp_example",
    "expires_at": "2099-01-01T00:00:00.000Z",
    "format": "text",
    "disclosure": "Sponsored",
    "test": true,
    "blocks": [
      {
        "type": "text",
        "role": "body",
        "spans": [
          {
            "text": "Try a service for your next trip.",
            "bold": true
          }
        ]
      },
      {
        "type": "buttons",
        "buttons": [
          {
            "id": "primary",
            "text": "Learn more",
            "style": "primary",
            "url": "https://example.com/offer"
          }
        ]
      },
      {
        "type": "text",
        "role": "footer",
        "spans": [
          {
            "text": "Sponsored · Sidekick"
          }
        ]
      }
    ]
  }
}

POST /api/v1/mobile/interact

{"delivery_id":"…","action":"…"}

action берётся из кнопки. Ответ: has_ad, ad. ID выдачи сохраняется. Повтор действия не создаёт второе начисление. URL-кнопки открывают исходный url, без запроса interact.

POST /api/v1/mobile/seen

{"delivery_id":"…","view":"…"}

Отправляется после непрерывного просмотра ≥50% карточки в течение 1 секунды, при активном экране и загруженных медиа. Kotlin View/Compose выполняют автоматически. Для своего UI необходим trackView(ad) либо seen с сервера.

Выдача не начисляет показ. Подтверждённый просмотр или действие начисляют его однократно. Повтор seen безопасен. Срок view может быть короче срока объявления.

Ограничения и ошибки

JSON ≤64 КиБ. Сессии: 120/мин на IP; операции: 120/мин на пользователя площадки; выдача: 30/мин. Автоматический повтор ads после сетевого сбоя не допускается.