# Миграция с API V1 на API V2

API V2 можно внедрять постепенно. V1-документация и существующие /ssapi/* интеграции остаются доступными, поэтому миграцию лучше начинать с нового placement, нового канала или ограниченного набора кампаний.

При миграции ориентируйтесь не только на замену URL, но и на новую форму payload: ctx, user.uid, user.ses, data[], customProps и tracking URL из ответа /choose.

В V1 контекст страницы передавался в context.page:

{
  "context": {
    "page": {
      "type": "PRODUCT",
      "data": ["sku-123"],
      "location": "https://example.com/product/sku-123"
    }
  }
}

В V2 тот же смысл передаётся в ctx:

{
  "ctx": {
    "type": "PRODUCT",
    "data": ["sku-123"],
    "location": "https://example.com/product/sku-123"
  }
}

В V1 часто использовались user.slid и session.sl. В V2 используйте user.uid и user.ses:

{
  "user": {
    "uid": "USER_UID",
    "ses": "SESSION_ID"
  }
}

После ответов API сохраняйте новые значения uid и ses, если Gateway вернул их в user.

В V1 custom event properties обычно передавались в events[].properties. В V2 события передаются в data[], а дополнительные свойства - в customProps:

{
  "data": [
    {
      "type": "purchase-v1",
      "name": "Purchase",
      "productId": "sku-123",
      "quantity": 1,
      "value": 1990,
      "currency": "RUB",
      "uniqueTransactionId": "order-100500",
      "customProps": {
        "paymentMethod": "card"
      }
    }
  ]
}

V1 selector request:

{
  "selector": {
    "names": ["homepage-recommendations"]
  }
}

V2 selector request:

{
  "data": [
    {
      "selector": "homepage-recommendations"
    }
  ]
}

Для in-app или trigger-based сценариев используйте activation flow:

1. Отправьте /visit или /event.
2. Получите campaigns[].campaignId.
3. Вызовите /choose с data[].campaignId.
4. Отрендерите контент и отправьте engagement по URL из ответа.

В V2 для ручного рендеринга включите:

{
  "options": {
    "isBuildEngagementUrl": true
  }
}

После этого Gateway добавит готовые tracking URL в ответ /choose. Используйте:

• content.events[].urls[] для content-level tracking;
• products.slots[].events[].urls[] для product-level tracking.

Не заменяйте product-level tracking content-level tracking-ом: для рекомендаций важно отправлять события конкретных слотов.

1. Выберите один selector или placement, который можно безопасно перевести на V2.
2. Реализуйте хранение uid и ses.
3. Замените context.page на ctx, selector.names на data[].selector.
4. Включите isBuildEngagementUrl и подключите вызов URL из content.events[] и products.slots[].events[].
5. Сравните показы, клики и бизнес-события в отчётах.
6. После проверки переносите следующие placements.

• ctx.type, ctx.data и ctx.location совпадают с настройками кампаний и фидом.
• uid сохраняется между сессиями, ses обновляется после ответов API.
• Для /choose с pageview используется isImplicitPageview только один раз на страницу.
• Для товаров отправляются products.slots[].events[], а не только content-level events.
• Для login/signup передаются одинаковые cuid и cuidType во всех каналах интеграции.