diff --git a/.gitbook/assets/image (1).png b/.gitbook/assets/image (1).png new file mode 100644 index 0000000..a529f4c Binary files /dev/null and b/.gitbook/assets/image (1).png differ diff --git a/.gitbook/assets/image (2).png b/.gitbook/assets/image (2).png new file mode 100644 index 0000000..8e1432e Binary files /dev/null and b/.gitbook/assets/image (2).png differ diff --git a/.gitbook/assets/image (3).png b/.gitbook/assets/image (3).png new file mode 100644 index 0000000..f82a325 Binary files /dev/null and b/.gitbook/assets/image (3).png differ diff --git a/.gitbook/assets/image.png b/.gitbook/assets/image.png new file mode 100644 index 0000000..d5eca9a Binary files /dev/null and b/.gitbook/assets/image.png differ diff --git a/README.md b/README.md index e69de29..d9fb602 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,59 @@ +--- +description: >- + На странице описываются термины, использующиеся более чем в одной системе + Retail Rocket +--- + +# Глоссарий Retail Rocket + +## Товар + +Товарное предложение интернет-магазина. + +## Групповой товар + +Товары разного размера или цвета, объединенные в группу. + +## Карточка товара + +Страница веб-сайта или экран мобильного приложения, на котором отображаются сведения о [товаре](./#tovar). + +## Карточка группового товара + +Страница веб-сайта или экран мобильного приложения, на котором отображаются сведения о [групповом товаре](./#gruppovoi-tovar). + +## Товарная категория + +Объединение товаров в рамках товарной категории (радиоуправляемые игрушки, молоко и т.д.). + +## Дерево товарных категорий + +Набор товарных категорий, объединенных в рамках древовидной структуры от общей товарной категории к частной. Например: Товары для дома -> Кухня -> Вилки. + +## Страница товарной категории + +Веб-страница или экран мобильного приложения, на котором отображаются товары, принадлежащие одной товарной категории. + +## Товарная база + +Для полноценной эффективной работы Retail Rocket требуется передать в систему товарную базу магазина. Из товарной базы магазина система формирует два основных набора данных: сведения о товарах и [дерево товарных категорий](./#derevo-tovarnykh-kategorii). + +Эти данные повышают качество рекомендаций, используются для фильтрации товарной выдачи от товаров вышедших из наличия и для отображения товарных предложений в письмах, веб-пушах и на сайте интернет магазина. + +## Пользовательское поведение + +Одно или более действий пользователя в интернет-магазине. Для системы Retail Rocket считаются значимыми следующие пользовательские действия в интернет-магазине: + +* Просмотр карточки товара; +* Просмотр карточки группового товара; +* Просмотр страницы товарной категории; +* Добавление товара в корзину; +* Совершение заказа; +* Ввод поисковой фразы. +* Аутификация пользователя + +## Контакт + +Система Retail Rocket позволяет коммуницировать с пользователями интернет-магазина через различные каналы: email, web-push, sms и т.д. Для того чтобы куммуникация была персонализированной, система позволяет накапливать и хранить данные полученные с сайта или других систем(кассовые аппараты, внешние системы CRM) о поведение пользователя на сайте, о его каналах коммуникация и его дополнительные данные. + +Совокупность накопленных данных о пользователе с каналами коммуникаций с ним, в системе Retail Rocket называется Контакт. diff --git a/SUMMARY.md b/SUMMARY.md new file mode 100644 index 0000000..485a34e --- /dev/null +++ b/SUMMARY.md @@ -0,0 +1,11 @@ +# Table of contents + +* [Глоссарий Retail Rocket](README.md) + +## Интеграция с Retail Rocket + +* [Общие принципы интеграции с Retail Rocket](integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket.md) +* [API трекинг пользовательского поведения](integraciya-s-retail-rocket/http-tracking-api.md) +* [Инструкция по интеграции продукта «Спонсорские размещения»](integraciya-s-retail-rocket/instrukciya-po-integracii-retail-rocket-sponsorskoe-razmeshenie.md) +* [API получения контента спонсорских размещений](integraciya-s-retail-rocket/api-sponsorskikh-razmeshenii.md) +* [API получения товарных рекомендаций](integraciya-s-retail-rocket/api-polucheniya-tovarnykh-rekomendacii.md) diff --git a/integraciya-s-retail-rocket/api-polucheniya-tovarnykh-rekomendacii.md b/integraciya-s-retail-rocket/api-polucheniya-tovarnykh-rekomendacii.md new file mode 100644 index 0000000..1375e10 --- /dev/null +++ b/integraciya-s-retail-rocket/api-polucheniya-tovarnykh-rekomendacii.md @@ -0,0 +1,622 @@ +# API получения товарных рекомендаций + +## **Общие концепции** + +Для получение товарных рекомендаций от системы Retail Rocket необходимо обратиться к ресурсу, соответствующему типу рекомендаций. + +API получения товарных рекомендаций **** придерживается [общих принципов интеграционных API](obshie-principy-integracii-s-retail-rocket.md). + +{% hint style="info" %} +**Товарные параметры** + +Параметр `stockId` требуется для того, чтобы рекомендации содержали только товары в наличии на конкретном складе (регионе). Значение параметра, как и все товарные параметры, должно соответствовать значениям, переданным в Retail Rocket с товарной базой. +{% endhint %} + +{% hint style="info" %} +**Лимит частоты обращения к ресурсам** + +По умолчанию установлен лимит в 100 обращений в секунду на магазин (`partnerId`) в целом. Для изменения лимита необходимо обратиться к вашему аккаунт-менеджеру или через форму поддержки в личном кабинете. +{% endhint %} + +{% hint style="warning" %} +**Управление кешированием** + +Вместе с возвращаемыми данными передается http-заголовок `Cache-Control,` которому необходимо следовать при кешировании полученных данных. +{% endhint %} + +### **Base URL** + +`https://externalapi.retailrocket.net/api/3.0/` + +### HTTP-метод доступа + +Все ресурсы API доступны только по `GET` методу + +### HTTP-статусы обращения + +Успешность обращение к ресурсу можно оценить по полученному HTTP-статусу: + +* **200 OK** - запрос принят; +* **400 BadRequest** - ошибка в запросе, необходимо проверить правильность построения запроса; +* **401 Unauthorized** - ошибка аутентификации, проверьте корректность пары `partnerId`, `apiKey;` +* **403 Forbidden** - доступ запрещен; +* **404 NotFound** - запрошенный ресурс не найден, необходимо проверить правильность URL; +* **429 TooManyRequest** - слишком много запросов и/или лимит на количество запросов в интервал времени превышен; + +### Возвращаемое значение + +В случае успешного обращения к любому ресурсу, HTTP-статус будет 200 Ok, а в теле запроса будет возвращена строка, содержащая JSON-объект. + +{% tabs %} +{% tab title="Пример возвращаемых данных" %} +```javascript +{ + "recommendations": + [ + { + "productId": [53242, 41231] + } + ] +} +``` +{% endtab %} + +{% tab title="JSON Schema" %} +```javascript +{ + "$schema": "https://json-schema.org/draft/2019-09/schema", + "type": "object", + "properties": { + "recommendations": { + "type": "array", + "items": { + "type": "object", + "properties": { + "productId": { + "type": "array", + "items": { + "type": "integer" + } + } + } + } + } + } +} +``` +{% endtab %} +{% endtabs %} + +Если рекомендаций по этим параметром нет, то вернётся пустой массив `recommendations` + +## Типы рекомендаций + +### **Популярные товары для главного экрана** + +Рассчитаны на основании поведения пользователя во всем интернет-магазине, без привязки к конкретным категориям, товарам, поисковым фразам т.д. + +Представляет из себя актуальные бестселлеры магазина. + +#### **Path** + +**`partnerRecommendations/popular`** + +#### Параметры строки запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](obshie-principy-integracii-s-retail-rocket.md#upravlenie-sessiei) | +| `stockId` | Нет | string | [Идентификатор склада/региона](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#podderzhka-regionalnosti-sklad-region) | + +#### Пример вызова + +```bash +curl 'https://externalapi.retailrocket.net/api/3.0/partnerRecommendations/popular/?sessionExternalId=3beb9714-82e9-4c08-938d-1391f5d86f2b&stockId=moscow&partnerId=69908d02c7d513ce40de715a&apiKey=5b333f5297a528b0184b6017' +``` + +### **Популярные товары для экрана** товарной категории + +Предназначен для показа пользователю самых популярных товаров в рамках категорийной группы. Учитываются товары и пользовательское поведение в рамках конкретной категории и всех ее подкатегорий. + +{% hint style="warning" %} +В зависимости от того, как выполнена интеграция передачи [товарной базы](obshie-principy-integracii-s-retail-rocket.md#tovarnaya-baza), необходимо вызывать разные методы для получения товарных рекомендаций для экрана товарной категории. + +[Интеграции через YML-файл](api-polucheniya-tovarnykh-rekomendacii.md#pri-integracii-cherez-yml-fail) + +[Интеграции через Product API](api-polucheniya-tovarnykh-rekomendacii.md#pri-integracii-cherez-product-api) +{% endhint %} + +#### При интеграции через YML-файл + +В YML файле доступно дерево категорий с целочисленными идентификаторами категории, поэтому и товары имеют целочисленные идентификаторы категорий, что позволяет использовать такие идентификаторы для запроса на получение товарных рекомендаций категории. + +#### Path + +**`categoryRecommendations/popular`** + +#### Параметры строки запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------------- | ------------ | :----------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](obshie-principy-integracii-s-retail-rocket.md#upravlenie-sessiei) | +| `categoryIds` | Да | number array | [Список идентификаторов товарных категорий, записанных через запятую](obshie-principy-integracii-s-retail-rocket.md#svedeniya-o-tovare) | +| `stockId` | Нет | string | [Идентификатор склада/региона](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#podderzhka-regionalnosti-sklad-region) | + +#### Пример вызова + +```bash +curl 'https://externalapi.retailrocket.net/api/3.0/categoryRecommendations/popular/?sessionExternalId=3beb9714-82e9-4c08-938d-1391f5d86f2b&stockId=moscow&partnerId=69908d02c7d513ce40de715a&apiKey=5b333f5297a528b0184b6017&categoryIds=123,234,254' +``` + +#### При интеграции через Product API + +При использовании product API категория передается как `categoryPath` также она должна быть передана и в метод для получения товарных рекомендаций. + +#### Path + +**`categoryRecommendations/popularByCategoryPath`** + +#### Параметры строки запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------------- | ------------ | :----------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](obshie-principy-integracii-s-retail-rocket.md#upravlenie-sessiei) | +| `categoryPaths` | Да | string array | [Список путей товарных категорий, записанных как несколько параметров через &](obshie-principy-integracii-s-retail-rocket.md#tovarnaya-baza) | +| `stockId` | Нет | string | [Идентификатор склада/региона](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#podderzhka-regionalnosti-sklad-region) | + +#### Пример вызова + +```bash +curl 'https://externalapi.retailrocket.net/api/3.0/categoryRecommendations/popularByCategoryPath/?sessionExternalId=73018148&categoryPaths=katinwinkel&categoryPaths=accu-gereedschap%2Faccu&apiKey=5b333f5697a528b0184b6017&partnerId=59908d02c7d013ce40de715a&session=5bb7b6201323790001561024' +``` + +### **Популярные товары со скидкой для экрана** товарной категории + +Предназначен для показа пользователю самых популярных товаров в рамках категорийной группы с учетом скидки. Учитываются товары со скидкой и пользовательское поведение в рамках конкретной категории и всех ее подкатегорий. + +{% hint style="warning" %} +В зависимости от того, как выполнена интеграция передачи [товарной базы](obshie-principy-integracii-s-retail-rocket.md#tovarnaya-baza), необходимо вызывать разные методы для получения товарных рекомендаций для экрана товарной категории. + +[Интеграции через YML-файл](api-polucheniya-tovarnykh-rekomendacii.md#pri-integracii-cherez-yml-fail-1) + +[Интеграции через Product API ](api-polucheniya-tovarnykh-rekomendacii.md#pri-integracii-cherez-product-api-1) +{% endhint %} + +#### При интеграции через YML-файл + +В YML файле доступно дерево категорий с целочисленными идентификаторами категории, поэтому и товары имеют целочисленные идентификаторы категорий, что позволяет использовать такие идентификаторы для запроса на получение товарных рекомендаций категории. + +#### Path + +**`categoryRecommendations/saleByPopular`** + +#### Параметры строки запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------------- | ------------ | :----------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](obshie-principy-integracii-s-retail-rocket.md#upravlenie-sessiei) | +| `categoryIds` | Да | number array | [Список идентификаторов товарных категорий, записанных через запятую](obshie-principy-integracii-s-retail-rocket.md#svedeniya-o-tovare) | +| `stockId` | Нет | string | [Идентификатор склада/региона](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#podderzhka-regionalnosti-sklad-region) | + +#### Пример вызова + +```bash +curl 'https://externalapi.retailrocket.net/api/3.0/categoryRecommendations/saleByPopular/?sessionExternalId=3beb9714-82e9-4c08-938d-1391f5d86f2b&stockId=moscow&partnerId=69908d02c7d513ce40de715a&apiKey=5b333f5297a528b0184b6017&categoryIds=123,234,254' +``` + +#### При интеграции через Product API + +При использовании product API категория передается как `categoryPath` также она должна быть передана и в метод для получения товарных рекомендаций. + +#### Path + +**`categoryRecommendations/saleByPopularByCategoryPath`** + +#### Параметры строки запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------------- | ------------ | :----------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](obshie-principy-integracii-s-retail-rocket.md#upravlenie-sessiei) | +| `categoryPaths` | Да | string array | [Список путей товарных категорий, записанных как несколько параметров через &](obshie-principy-integracii-s-retail-rocket.md#tovarnaya-baza) | +| `stockId` | Нет | string | [Идентификатор склада/региона](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#podderzhka-regionalnosti-sklad-region) | + +#### Пример вызова + +```bash +curl 'https://externalapi.retailrocket.net/api/3.0/categoryRecommendations/saleByPopularByCategoryPath/?sessionExternalId=73018148&categoryPaths=katinwinkel&categoryPaths=accu-gereedschap%2Faccu&apiKey=5b333f5697a528b0184b6017&partnerId=59908d02c7d013ce40de715a&session=5bb7b6201323790001561024' +``` + +### **Поисковые рекомендации** + +Предназначен для показа пользователю товаров, наиболее подходящих под его поисковый запрос. Рекомендации рассчитываются на основе поведения других пользователей с подобным поисковым запросом и не учитывают смысл поисковых фраз. + +Поисковые рекомендации следует применять там, где известен поисковый запрос пользователя. Обычно это поисковый экран интернет-магазина. Рекомендации показывают свою эффективность, как и в роли дополнения к поисковой выдаче, так и в случае отсутствия поисковой выдачи. + +#### **Path** + +**`searchRecommendations/search`** + +#### Параметры строки запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](obshie-principy-integracii-s-retail-rocket.md#upravlenie-sessiei) | +| `stockId` | Нет | string | [Идентификатор склада/региона](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#podderzhka-regionalnosti-sklad-region) | +| `searchPhrase` | Да | string | Поисковый запрос пользователя | + +#### Пример вызова + +```bash +curl 'https://externalapi.retailrocket.net/api/3.0/searchRecommendations/search/?sessionExternalId=3beb9714-82e9-4c08-938d-1391f5d86f2b&stockId=moscow&partnerId=69908d02c7d513ce40de715a&apiKey=5b333f5297a528b0184b6017&searchPhrase=skirts' +``` + +### **Похожие товары** + +Предназначен для показа товаров, наиболее похожих на просматриваемый пользователем товар. Рекомендации рассчитываются на основе поведения других пользователей и учитывают параметры товаров и настройки бизнес-правил в личном кабинете Retail Rocket. + +#### **Path** + +**`productRecommendations/alternatives`** + +#### Параметры строки запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](obshie-principy-integracii-s-retail-rocket.md#upravlenie-sessiei) | +| `stockId` | Нет | string | [Идентификатор склада/региона](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#podderzhka-regionalnosti-sklad-region) | +| `productIds` | Да | number array | [Список идентификаторов товара записанных через запятую](obshie-principy-integracii-s-retail-rocket.md#svedeniya-o-tovare) | + +#### Пример вызова + +```bash +curl 'https://externalapi.retailrocket.net/api/3.0/productRecommendations/alternatives/?sessionExternalId=3beb9714-82e9-4c08-938d-1391f5d86f2b&stockId=moscow&partnerId=69908d02c7d513ce40de715a&apiKey=5b333f5297a528b0184b6017&productIds=93845,93846,93847' +``` + +### **Сопутствующие товары** + +Предназначен для показа комплементарных товаров к товару или товарам. Рекомендации рассчитываются на основание поведения других пользователей и учитывают параметры товаров и настройки бизнес-правил в личном кабинете Retail Rocket. + +#### **Path** + +**`productRecommendations/related`** + +#### Параметры строки запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](obshie-principy-integracii-s-retail-rocket.md#upravlenie-sessiei) | +| `stockId` | Нет | string | [Идентификатор склада/региона](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#podderzhka-regionalnosti-sklad-region) | +| `productIds` | Да | number array | [Список идентификаторов товара записанных через запятую](obshie-principy-integracii-s-retail-rocket.md#svedeniya-o-tovare) | + +#### Пример вызова + +```bash +curl 'https://externalapi.retailrocket.net/api/3.0/productRecommendations/relatedByInterestedProperties/?sessionExternalId=3beb9714-82e9-4c08-938d-1391f5d86f2b&stockId=moscow&partnerId=69908d02c7d513ce40de715a&apiKey=5b333f5297a528b0184b6017&productIds=93845,93846,93847' +``` + +### **Сопутствующие товары, персонализированные с учетом интереса пользователя к свойствам товара** + +Предназначен для показа комплементарных товаров к товару или товарам, **** которые дополнительно ранжированны в зависимости от интереса пользователей к конкретным свойствам товара (размер, цвет). Рекомендации рассчитываются на основании поведения других пользователей и учитывают параметры товаров и настройки бизнес-правил в личном кабинете Retail Rocket. + +#### **Path** + +**`productRecommendations/relatedByInterestedProperties`** + +#### Параметры строки запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](obshie-principy-integracii-s-retail-rocket.md#upravlenie-sessiei) | +| `stockId` | Нет | string | [Идентификатор склада/региона](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#podderzhka-regionalnosti-sklad-region) | +| `productIds` | Да | number array | [Список идентификаторов товара, записанных через запятую](obshie-principy-integracii-s-retail-rocket.md#svedeniya-o-tovare) | + +#### Пример вызова + +```bash +curl 'https://externalapi.retailrocket.net/api/3.0/productRecommendations/relatedByInterestedProperties/?sessionExternalId=3beb9714-82e9-4c08-938d-1391f5d86f2b&stockId=moscow&partnerId=69908d02c7d513ce40de715a&apiKey=5b333f5297a528b0184b6017&productIds=93845,93846,93847' +``` + +### **Персональные рекомендации** + +Алгоритм персональных рекомендаций возвращает наиболее интересные товары для пользователя. + +#### **Path** + +**`partnerRecommendations/personalComposite`** + +#### Параметры строки запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](obshie-principy-integracii-s-retail-rocket.md#upravlenie-sessiei) | +| `stockId` | Нет | string | [Идентификатор склада/региона](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#podderzhka-regionalnosti-sklad-region) | + +#### Пример вызова + +```bash +curl 'https://externalapi.retailrocket.net/api/3.0/partnerRecommendations/personalComposite/?sessionExternalId=3beb9714-82e9-4c08-938d-1391f5d86f2b&stockId=moscow&partnerId=69908d02c7d513ce40de715a&apiKey=5b333f5297a528b0184b6017' +``` + +### **Ранее купленные пользователем товары** + +Алгоритм возвращает ранее заказанные пользователем товары. + +#### **Path** + +**`partnerRecommendations/personalOrdered`** + +#### Параметры строки запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](obshie-principy-integracii-s-retail-rocket.md#upravlenie-sessiei) | +| `stockId` | Нет | string | [Идентификатор склада/региона](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#podderzhka-regionalnosti-sklad-region) | + +#### Пример вызова + +```bash +curl 'https://externalapi.retailrocket.net/api/3.0/partnerRecommendations/personalOrdered/?sessionExternalId=3beb9714-82e9-4c08-938d-1391f5d86f2b&stockId=moscow&partnerId=69908d02c7d513ce40de715a&apiKey=5b333f5297a528b0184b6017'' +``` + +### **Аксессуары** + +Предназначен для показа товаров из аксессуарных категорий, которые приобретаются совместно с товаром или товарами, к которым запрашиваются рекомендации. Рекомендации рассчитываются на основании поведения других пользователей и учитывают параметры товаров и настройки бизнес-правил в личном кабинете Retail Rocket. + +#### Path + +**`productRecommendations/accessories`** + +#### Параметры строки запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](obshie-principy-integracii-s-retail-rocket.md#upravlenie-sessiei) | +| `stockId` | Нет | string | [Идентификатор склада/региона](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#podderzhka-regionalnosti-sklad-region) | +| `productIds` | Да | number array | [Список идентификаторов товара записанных через запятую](obshie-principy-integracii-s-retail-rocket.md#svedeniya-o-tovare) | + +#### Пример вызова + +```bash +curl 'https://externalapi.retailrocket.net/api/3.0/productRecommendations/accessories/?sessionExternalId=3beb9714-82e9-4c08-938d-1391f5d86f2b&stockId=moscow&partnerId=69908d02c7d513ce40de715a&apiKey=5b333f5297a528b0184b6017&productIds=93845,93846,93847' +``` + +### Популярные товары к интересующим пользователя категориям + +Retail Rocket в реальном времени анализирует интересы пользователя и строит связи «пользователь» – «категория». Это позволяет демонстрировать хиты продаж только из категорий, которые наиболее интересны данному пользователю в долгосрочной перспективе. + +#### Path + +**`partnerRecommendations/popularInInterestedCategories`** + +#### Параметры строки запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](obshie-principy-integracii-s-retail-rocket.md#upravlenie-sessiei) | +| `stockId` | Нет | string | [Идентификатор склада/региона](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#podderzhka-regionalnosti-sklad-region) | + +#### Пример вызова + +```bash +curl 'https://externalapi.retailrocket.net/api/3.0/partnerRecommendations/popularInInterestedCategories/?sessionExternalId=3beb9714-82e9-4c08-938d-1391f5d86f2b&stockId=moscow&partnerId=69908d02c7d513ce40de715a&apiKey=5b333f5297a528b0184b6017' +``` + +### Просмотренные товары + +Алгоритм возвращает просмотренные пользователем товары. + +#### Path + +**`partnerRecommendations/personalViewed`** + +#### Параметры строки запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](obshie-principy-integracii-s-retail-rocket.md#upravlenie-sessiei) | +| `stockId` | Нет | string | [Идентификатор склада/региона](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#podderzhka-regionalnosti-sklad-region) | + +#### Пример вызова + +```bash +curl 'https://externalapi.retailrocket.net/api/3.0/partnerRecommendations/personalViewed/?sessionExternalId=3beb9714-82e9-4c08-938d-1391f5d86f2b&stockId=moscow&partnerId=69908d02c7d513ce40de715a&apiKey=5b333f5297a528b0184b6017' +``` + +### Сопутствующие товары из категорий, отличных от категории текущего товара + +Алгоритм возвращает сопутствующие товарные позиции, которые с максимальной вероятностью могут быть куплены вместе с товаром, к которому запрошены рекомендации. Из рекомендаций сопутствующих товаров удаляются товары, принадлежащие той же категории, что и текущий товар. + +#### Path + +**`productRecommendations/relatedWithoutCurrentCategory`** + +#### Параметры строки запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](obshie-principy-integracii-s-retail-rocket.md#upravlenie-sessiei) | +| `stockId` | Нет | string | [Идентификатор склада/региона](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#podderzhka-regionalnosti-sklad-region) | +| `productIds` | Да | number array | [Список идентификаторов товара записанных через запятую](obshie-principy-integracii-s-retail-rocket.md#svedeniya-o-tovare) | + +#### Пример вызова + +```bash +curl 'https://externalapi.retailrocket.net/api/3.0/productRecommendations/relatedWithoutCurrentCategory/?sessionExternalId=3beb9714-82e9-4c08-938d-1391f5d86f2b&stockId=moscow&partnerId=69908d02c7d513ce40de715a&apiKey=5b333f5297a528b0184b6017&productIds=1254,2345,5484' +``` + +### Сопутствующие товары с учетом бизнес-правил + +Алгоритм возвращает сопутствующие товарные позиции, которые с максимальной вероятностью могут быть куплены вместе с товаром, к которому запрошены рекомендации. При этом данный алгоритм учитывает бизнес-правила и позволяет: + +* Продвинуть товары из непопулярных категорий (например, новая категория товаров в ассортименте); +* Реализовать “экспертные рекомендации” при продаже технически сложных товаров, когда покупатель может не знать что именно нужно докупить учесть пожелания партнера к подбору сопутствующих товаров; + +#### Path + +**`productRecommendations/relatedWithRules`** + +#### Параметры строки запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](obshie-principy-integracii-s-retail-rocket.md#upravlenie-sessiei) | +| `stockId` | Нет | string | [Идентификатор склада/региона](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#podderzhka-regionalnosti-sklad-region) | +| `productIds` | Да | number array | [Список идентификаторов товара записанных через запятую](obshie-principy-integracii-s-retail-rocket.md#svedeniya-o-tovare) | + +#### Пример вызова + +```bash +curl 'https://externalapi.retailrocket.net/api/3.0/productRecommendations/relatedWithRules/?sessionExternalId=3beb9714-82e9-4c08-938d-1391f5d86f2b&stockId=moscow&partnerId=69908d02c7d513ce40de715a&apiKey=5b333f5297a528b0184b6017&productIds=1254,2345,5484' +``` + +### Новинки в категории + +Алгоритм возвращает новинки в категории. + +{% hint style="warning" %} +В зависимости от того, как выполнена интеграция передачи [товарной базы](obshie-principy-integracii-s-retail-rocket.md#tovarnaya-baza), необходимо вызывать разные методы для получения товарных рекомендаций для экрана товарной категории. + +[Интеграции через YML-файл](api-polucheniya-tovarnykh-rekomendacii.md#pri-integracii-cherez-yml-fail-2) + +[Интеграции через Product API ](api-polucheniya-tovarnykh-rekomendacii.md#pri-integracii-cherez-product-api-2) +{% endhint %} + +#### При интеграции через YML-файл + +В YML файле доступно дерево категорий с целочисленными идентификаторами категории, поэтому и товары имеют целочисленные идентификаторы категорий, что позволяет использовать такие идентификаторы для запроса на получение товарных рекомендаций категории. + +#### Path + +**`categoryRecommendations/latest`** + +#### Параметры строки запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](obshie-principy-integracii-s-retail-rocket.md#upravlenie-sessiei) | +| `stockId` | Нет | string | [Идентификатор склада/региона](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#podderzhka-regionalnosti-sklad-region) | +| `categoryIds` | Да | number array | [Список идентификаторов товарных категорий, записанных через запятую](obshie-principy-integracii-s-retail-rocket.md#svedeniya-o-tovare) | + +#### Пример вызова + +```bash +curl 'https://externalapi.retailrocket.net/api/3.0/categoryRecommendations/latest/?sessionExternalId=3beb9714-82e9-4c08-938d-1391f5d86f2b&stockId=moscow&partnerId=69908d02c7d513ce40de715a&apiKey=5b333f5297a528b0184b6017&categoryIds=1254,2345,5484' +``` + +#### При интеграции через Product API + +При использовании product API категория передается как `categoryPath` также она должна быть передана и в метод для получения товарных рекомендаций. + +#### Path + +**`categoryRecommendations/latestByCategoryPath`** + +#### Параметры строки запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](obshie-principy-integracii-s-retail-rocket.md#upravlenie-sessiei) | +| `stockId` | Нет | string | [Идентификатор склада/региона](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#podderzhka-regionalnosti-sklad-region) | +| `categoryPaths` | Да | string array | [Список путей товарных категорий, записанных как несколько параметров через &](obshie-principy-integracii-s-retail-rocket.md#tovarnaya-baza) | + +#### Пример вызова + +```bash +curl 'https://externalapi.retailrocket.net/api/3.0/categoryRecommendations/latestByCategoryPath/?sessionExternalId=3beb9714-82e9-4c08-938d-1391f5d86f2b&stockId=moscow&partnerId=69908d02c7d513ce40de715a&apiKey=5b333f5297a528b0184b6017&categoryPaths=accu-gereedschap%2Faccu' +``` + +### Новинки со скидками + +Алгоритм возвращает новинки по категориям со скидками. + +{% hint style="warning" %} +В зависимости от того, как выполнена интеграция передачи [товарной базы](https://app.gitbook.com/s/-MYtMBMe1CFjdXfHKdxi/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket.md#tovarnaya-baza), необходимо вызывать разные методы для получения товарных рекомендаций для экрана товарной категории. + +[Интеграции через YML-файл](https://app.gitbook.com/s/-MYtMBMe1CFjdXfHKdxi/integraciya-s-retail-rocket/api-polucheniya-tovarnykh-rekomendacii.md#pri-integracii-cherez-yml-fail-2) + +[Интеграции через Product API ](https://app.gitbook.com/s/-MYtMBMe1CFjdXfHKdxi/integraciya-s-retail-rocket/api-polucheniya-tovarnykh-rekomendacii.md#pri-integracii-cherez-product-api-2) +{% endhint %} + +**При интеграции через YML-файл** + +В YML файле доступно дерево категорий с целочисленными идентификаторами категории, поэтому и товары имеют целочисленные идентификаторы категорий, что позволяет использовать такие идентификаторы для запроса на получение товарных рекомендаций категории. + +**Path** + +**`categoryRecommendations/saleByLatest`** + +**Параметры строки запроса** + +| Имя параметра | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `apiKey` | Да | string | [Ключ авторизации](https://app.gitbook.com/s/-MYtMBMe1CFjdXfHKdxi/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](https://app.gitbook.com/s/-MYtMBMe1CFjdXfHKdxi/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](https://app.gitbook.com/s/-MYtMBMe1CFjdXfHKdxi/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket.md#upravlenie-sessiei) | +| `stockId` | Нет | string | [Идентификатор склада/региона](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#podderzhka-regionalnosti-sklad-region) | +| `categoryIds` | Да | number array | [Список идентификаторов товарных категорий, записанных через запятую](https://app.gitbook.com/s/-MYtMBMe1CFjdXfHKdxi/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket.md#svedeniya-o-tovare) | + +**Пример вызова** + +```bash +curl 'https://externalapi.retailrocket.net/api/3.0/categoryRecommendations/saleByLatest/?sessionExternalId=3beb9714-82e9-4c08-938d-1391f5d86f2b&stockId=moscow&partnerId=69908d02c7d513ce40de715a&apiKey=5b333f5297a528b0184b6017&categoryIds=1254,2345,5484' +``` + +**При интеграции через Product API** + +При использовании product API категория передается как `categoryPath` также она должна быть передана и в метод для получения товарных рекомендаций. + +**Path** + +**`categoryRecommendations/saleByLatestByCategoryPath`** + +**Параметры строки запроса** + +| Имя параметра | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](https://app.gitbook.com/s/-MYtMBMe1CFjdXfHKdxi/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](https://app.gitbook.com/s/-MYtMBMe1CFjdXfHKdxi/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](https://app.gitbook.com/s/-MYtMBMe1CFjdXfHKdxi/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket.md#upravlenie-sessiei) | +| `stockId` | Нет | string | [Идентификатор склада/региона](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#podderzhka-regionalnosti-sklad-region) | +| `categoryPaths` | Да | string array | [Список путей товарных категорий, записанных как несколько параметров через &](https://app.gitbook.com/s/-MYtMBMe1CFjdXfHKdxi/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket.md#tovarnaya-baza) | + +**Пример вызова** + +```bash +curl 'https://externalapi.retailrocket.net/api/3.0/categoryRecommendations/saleByLatestByCategoryPath/?sessionExternalId=3beb9714-82e9-4c08-938d-1391f5d86f2b&stockId=moscow&partnerId=69908d02c7d513ce40de715a&apiKey=5b333f5297a528b0184b6017&categoryPaths=accu-gereedschap%2Faccu' +``` diff --git a/integraciya-s-retail-rocket/api-sponsorskikh-razmeshenii.md b/integraciya-s-retail-rocket/api-sponsorskikh-razmeshenii.md new file mode 100644 index 0000000..b6a7c14 --- /dev/null +++ b/integraciya-s-retail-rocket/api-sponsorskikh-razmeshenii.md @@ -0,0 +1,486 @@ +# API получения контента спонсорских размещений + +## Общие рекомендации по интеграции + +При интеграции API на рекламную площадку, необходимо помнить, что обращение к внешнему API всегда может закончиться неудачно. +Причин для этого множество - нестабильность сетевой инфраструктуры, блокировки Роскомнадзора, ошибки на стороне сервера или просто человеческий фактор. +Поэтому мы рекомендуем учитывать возможность получения нестандартного ответа, и прорабатывать это с точки зрения внешнего вида веб-сайта или мобильного приложения. +Это особенно важно для главной страницы - если промо материал занимает большую часть экрана, то, возможно, следует предусмотреть заполнение этого пространства содержимым по умолчанию. + +Обязательно нужно устанавливать какой-то разумный таймаут на все внешние запросы, чтобы сохранить отзывчивость интерфейса. + +Так же, стоит не забывать, что получение пустого промо материала (ответ 204) - это вполне стандартная и частая ситуация, которая возникает, если для запрашиваемого сегмента пользователей не запущено ни одной кампании. + +Стоит предусмотреть возможность того, что результат запроса может иметь неожиданный формат. Кампании могут предоставлять разные варианты содержимого, представленные в различной форме. Это могут быть баннеры, товарные полки, брендированные товарные полки, и т.д. Для кажого варианта содержимого будет своя логика отрисовки и учета факта просмотра. +Варианты этого содержимого всегда ограничиваются параметром `acceptContent`, что гарантирует предсказумость результата запроса, однако общей практикой является предусмотреть и обработать неизвестный формат содержимого. + +## Термины + +### **Рекламная площадка** + +Магазин, предоставляющий страницы своего web или мобильного приложения для размещения рекламных объявлений. Обладает идентификатором `partnerId`, который можно получить в личном кабинете или у аккаунт-менеджера. + +**Рекламодатель**: лицо/организация, которая заинтересована в том, чтобы показывать на рекламных площадках свое содержимое, чтобы достигать маркетинговые цели. + +### **Содержимое для показа** + +Объект, содержащий необходимые данные для показа пользователю рекламной площадки. Запрашивается рекламной площадкой у API спонсорских размещений. Показывается рекламной площадкой с целью получить плату от рекламодателя за просмотр этого содержимого пользователем площадки. + +При запросе необходимо использовать параметр строки запроса `acceptContent` для указания типа содержимого, который рекламная площадка готова разместить. + +Значения `acceptContent`: + +* `string` +* `productIds` +* `banners` +* `sharedBanners` + +Если рекламная площадка готова размещать более одного варианта содержимого, их можно указать через запятую, например: `acceptContent=string,productIds` + +### **Рекламное место** +**** +Область страницы web-приложения или экрана мобильного приложения рекламной площадки, предназначенная для размещения там платного содержимого. Бывает разных типов в зависимости от вида, места, области размещения: + +* **any placement –** место размещения рекламы, которое может находиться в любом разделе веб-сайта или мобильного приложения; +* **product placement** – место размещения в контексте карточки товара; +* **category placement** – место размещения в контексте категории; +* **search placement** – место размещения в контексте поисковой выдачи; +* **product group placement** – место размещения в контексте группы товаров, например, это может быть корзина или страница успешного завершения заказа. + +### **Товар** + +Позиция товарного каталога рекламной площадки. Обладает идентификатором `productId` типа «64-разрядное целое со знаком». + +### **Категория** + +Группа товаров, содержащая произвольный (существенный для рекламной площадки) признак. Обладает идентификатором `categoryId` типа «64-разрядное целое со знаком». Предоставляется рекламной площадкой. + +## Base URL + +`https://visitors-sp.retailrocket.net/v1/` + +## Resources + +### Спонсорский контент для товарных страниц + +#### Path + +`partners/{partnerId}/productPlacements/{placementId}/impressions` + +#### Http Method + +`GET` + +#### Параметры пути запроса + +| Имя поля | Тип | Описание | +| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `partnerId` | string | [Идентификатор интернет-магазина](https://github.com/RetailRocket/Documentation/tree/117692a06b3c513e32856a45dee367feafada3cb/obshie-principy-integracii-s-retail-rocket/README.md#identifikator-internet-magazina) | +| `placementId` | string | Идентификатор места размещения. Выдается сотрудником Retail Rocket | + +#### Параметры строки запроса + +| Имя поля | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](https://github.com/RetailRocket/Documentation/tree/117692a06b3c513e32856a45dee367feafada3cb/obshie-principy-integracii-s-retail-rocket/README.md#upravlenie-sessiei) | +| `acceptContent` | Да | string | Типы содержимого, которые площадка готова разместить. Через запятую | +| `apiKey` | Да | string | [Ключ авторизации](https://github.com/RetailRocket/Documentation/tree/117692a06b3c513e32856a45dee367feafada3cb/obshie-principy-integracii-s-retail-rocket/README.md#avtorizaciya) | +| `productId` | Да | integer | [Идентификатор товара, в контексте которого находится пользователь](obshie-principy-integracii-s-retail-rocket.md#svedeniya-o-tovare) | +| `stockId` | Нет | string | [Идентификатор склада, в контексте которого находится пользователь](obshie-principy-integracii-s-retail-rocket.md#svedeniya-o-tovare) | + +#### **Тип ответа** + +* [Impression](api-sponsorskikh-razmeshenii.md#impression) + +#### Пример вызова + +```bash +curl 'https://visitors-sp.retailrocket.net/v1/partners/608423a9b126ac6ab3f8f0a5/productPlacements/a2837ec9-b000-46d7-9272-f64df080da51/impressions?apiKey=608423a104249fa8e9952323&sessionExternalId=3beb9714-82e9-4c08-938d-1391f5d86f2b&acceptContent=productIds,string&productId=93845&stockId=berlin13' +``` + +### Спонсорский контент для страниц групповых товаров + +#### Path + +`partners/{partnerId}/productGroupPlacements/{placementId}/impressions` + +#### Http Method + +`GET` + +#### Параметры пути запроса + +| Имя поля | Тип | Описание | +| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `partnerId` | string | [Идентификатор интернет-магазина](https://github.com/RetailRocket/Documentation/tree/117692a06b3c513e32856a45dee367feafada3cb/obshie-principy-integracii-s-retail-rocket/README.md#identifikator-internet-magazina) | +| `placementId` | string | Идентификатор места размещения. Выдается сотрудником Retail Rocket | + +#### Параметры строки запроса + +| Имя поля | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](https://github.com/RetailRocket/Documentation/tree/117692a06b3c513e32856a45dee367feafada3cb/obshie-principy-integracii-s-retail-rocket/README.md#upravlenie-sessiei) | +| `acceptContent` | Да | string | Типы содержимого, которые площадка готова разместить. Через запятую | +| `apiKey` | Да | string | [Ключ авторизации](https://github.com/RetailRocket/Documentation/tree/117692a06b3c513e32856a45dee367feafada3cb/obshie-principy-integracii-s-retail-rocket/README.md#avtorizaciya) | +| `productIds` | Да | number array | [Список идентификаторов товаров](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#svedeniya-o-tovare) | +| `stockId` | Нет | string | [Идентификатор склада, в контексте которого находится пользователь](obshie-principy-integracii-s-retail-rocket.md#svedeniya-o-tovare) | + +#### **Тип ответа** + +* [Impression](api-sponsorskikh-razmeshenii.md#impression) + +#### Пример вызова + +```bash +curl 'https://visitors-sp.retailrocket.net/v1/partners/608423a9b126ac6ab3f8f0a5/productGroupPlacements/545f2f85-dcbe-4d2d-8260-6ecdf6c8c415/impressions?apiKey=608423a104249fa8e9952323&sessionExternalId=3beb9714-82e9-4c08-938d-1391f5d86f2b&acceptContent=productIds,string&productIds=93845,93846,93847&stockId=berlin13' +``` + +### Спонсорский контент для страниц товарных категорий + +{% hint style="warning" %} +В зависимости от того, как выполнена интеграция [товарной базы](../#tovarnaya-baza), необходимо передавать определенный тип идентификатора категории в запросе спонсорского контента для страницы товарной категории. + +[Интеграции через YML-файл](api-sponsorskikh-razmeshenii.md#pri-integracii-cherez-yml-fail) + +[Интеграции через Product API](api-sponsorskikh-razmeshenii.md#pri-integracii-cherez-product-api) +{% endhint %} + +#### При интеграции через YML-файл + +В YML файле доступно дерево категорий с целочисленными идентификаторами категории, поэтому и товары имеют целочисленные идентификаторы категорий, что позволяет использовать такие идентификаторы для запроса спонсорского контента для страниц товарных категорий. + +#### Path + +`partners/{partnerId}/categoryPlacements/{placementId}/impressions` + +#### Http Method + +`GET` + +#### Параметры пути запроса + +| Имя поля | Тип | Описание | +| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `partnerId` | string | [Идентификатор интернет-магазина](https://github.com/RetailRocket/Documentation/tree/117692a06b3c513e32856a45dee367feafada3cb/obshie-principy-integracii-s-retail-rocket/README.md#identifikator-internet-magazina) | +| `placementId` | string | Идентификатор места размещения. Выдается сотрудником Retail Rocket | + +#### Параметры строки запроса + +| Имя поля | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](https://github.com/RetailRocket/Documentation/tree/117692a06b3c513e32856a45dee367feafada3cb/obshie-principy-integracii-s-retail-rocket/README.md#upravlenie-sessiei) | +| `acceptContent` | Да | string | Типы содержимого, которые площадка готова разместить. Через запятую | +| `apiKey` | Да | string | [Ключ авторизации](https://github.com/RetailRocket/Documentation/tree/117692a06b3c513e32856a45dee367feafada3cb/obshie-principy-integracii-s-retail-rocket/README.md#avtorizaciya) | +| `categoryId` | Да | integer | [Идентификатор категории, в контексте которой находится пользователь](../#derevo-tovarnykh-kategorii) | +| `stockId` | Нет | string | [Идентификатор склада, в контексте которого находится пользователь](obshie-principy-integracii-s-retail-rocket.md#svedeniya-o-tovare) | + +#### **Тип ответа** + +* [Impression](api-sponsorskikh-razmeshenii.md#impression) + +#### Пример вызова + +```bash +curl 'https://visitors-sp.retailrocket.net/v1/partners/608423a9b126ac6ab3f8f0a5/categoryPlacements/b17d8910-d0c5-4fd7-97d0-66b314f797f2/impressions?apiKey=608423a104249fa8e9952323&sessionExternalId=3beb9714-82e9-4c08-938d-1391f5d86f2b&acceptContent=productIds,string&categoryId=65' +``` + +#### При интеграции через Product API + +При использовании Product API категория передается как `categoryPath,` она должна быть передана в таком же виде и при запросе спонсорского контента для страницы товарной категории. + +#### Path + +`partners/{partnerId}/categoryPlacements/{placementId}/impressions` + +#### Http Method + +`GET` + +#### Параметры пути запроса + +| Имя поля | Тип | Описание | +| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `partnerId` | string | [Идентификатор интернет-магазина](https://github.com/RetailRocket/Documentation/tree/117692a06b3c513e32856a45dee367feafada3cb/obshie-principy-integracii-s-retail-rocket/README.md#identifikator-internet-magazina) | +| `placementId` | string | Идентификатор места размещения. Выдается сотрудником Retail Rocket | + +#### Параметры строки запроса + +| Имя поля | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](https://github.com/RetailRocket/Documentation/tree/117692a06b3c513e32856a45dee367feafada3cb/obshie-principy-integracii-s-retail-rocket/README.md#upravlenie-sessiei) | +| `acceptContent` | Да | string | Типы содержимого, которые площадка готова разместить. Через запятую | +| `apiKey` | Да | string | [Ключ авторизации](https://github.com/RetailRocket/Documentation/tree/117692a06b3c513e32856a45dee367feafada3cb/obshie-principy-integracii-s-retail-rocket/README.md#avtorizaciya) | +| `categoryPath` | Да | string | [Путь категории товара](../#derevo-tovarnykh-kategorii) | +| `stockId` | Нет | string | [Идентификатор склада, в контексте которого находится пользователь](obshie-principy-integracii-s-retail-rocket.md#svedeniya-o-tovare) | + +#### **Тип ответа** + +* [Impression](api-sponsorskikh-razmeshenii.md#impression) + +#### Пример вызова + +```bash +curl 'https://visitors-sp.retailrocket.net/v1/partners/608423a9b126ac6ab3f8f0a5/categoryPlacements/b17d8910-d0c5-4fd7-97d0-66b314f797f2/impressions?apiKey=608423a104249fa8e9952323&sessionExternalId=3beb9714-82e9-4c08-938d-1391f5d86f2b&acceptContent=productIds,string&categoryPath=Electronics%2FTV' +``` + +### Спонсорский контент для страницы поиска + +#### Path + +`partners/{partnerId}/searchPlacements/{placementId}/impressions` + +#### Http Method + +`GET` + +#### Параметры пути запроса + +| Имя поля | Тип | Описание | +| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `partnerId` | string | [Идентификатор интернет-магазина](https://github.com/RetailRocket/Documentation/tree/117692a06b3c513e32856a45dee367feafada3cb/obshie-principy-integracii-s-retail-rocket/README.md#identifikator-internet-magazina) | +| `placementId` | string | Идентификатор места размещения. Выдается сотрудником Retail Rocket | + +#### Параметры строки запроса + +| Имя поля | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](https://github.com/RetailRocket/Documentation/tree/117692a06b3c513e32856a45dee367feafada3cb/obshie-principy-integracii-s-retail-rocket/README.md#upravlenie-sessiei) | +| `acceptContent` | Да | string | Типы содержимого, которые площадка готова разместить. Через запятую | +| `apiKey` | Да | string | [Ключ авторизации](https://github.com/RetailRocket/Documentation/tree/117692a06b3c513e32856a45dee367feafada3cb/obshie-principy-integracii-s-retail-rocket/README.md#avtorizaciya) | +| `searchQuery` | Да | string | Поисковый запрос, который ввел пользователь | +| `stockId` | Нет | string | [Идентификатор склада, в контексте которого находится пользователь](obshie-principy-integracii-s-retail-rocket.md#svedeniya-o-tovare) | + +#### **Тип ответа** + +* [Impression](api-sponsorskikh-razmeshenii.md#impression) + +```bash +curl 'https://visitors-sp.retailrocket.net/v1/partners/608423a9b126ac6ab3f8f0a5/searchPlacements/d34fa7a5-26fe-4cd4-af3f-a52362d90c80/impressions?apiKey=608423a104249fa8e9952323&sessionExternalId=3beb9714-82e9-4c08-938d-1391f5d86f2b&acceptContent=productIds,string&searchQuery=Red%20Apples' +``` + +### Спонсорский контент для прочих страниц + +#### Path + +`partners/{partnerId}/anyPlacements/{placementId}/impressions` + +#### Http Method + +`GET` + +#### Параметры пути запроса + +| Имя поля | Тип | Описание | +| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `partnerId` | string | [Идентификатор интернет-магазина](https://github.com/RetailRocket/Documentation/tree/117692a06b3c513e32856a45dee367feafada3cb/obshie-principy-integracii-s-retail-rocket/README.md#identifikator-internet-magazina) | +| `placementId` | string | Идентификатор места размещения. Выдается сотрудником Retail Rocket | + +#### Параметры строки запроса + +| Имя поля | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](https://github.com/RetailRocket/Documentation/tree/117692a06b3c513e32856a45dee367feafada3cb/obshie-principy-integracii-s-retail-rocket/README.md#upravlenie-sessiei) | +| `acceptContent` | Да | string | Типы содержимого, которые площадка готова разместить, через запятую | +| `apiKey` | Да | string | [Ключ авторизации](https://github.com/RetailRocket/Documentation/tree/117692a06b3c513e32856a45dee367feafada3cb/obshie-principy-integracii-s-retail-rocket/README.md#avtorizaciya) | +| `stockId` | Нет | string | [Идентификатор склада, в контексте которого находится пользователь](obshie-principy-integracii-s-retail-rocket.md#svedeniya-o-tovare) | + +#### **Тип ответа** + +* [Impression](api-sponsorskikh-razmeshenii.md#impression) + +#### Пример вызова + +```bash +curl 'https://visitors-sp.retailrocket.net/v1/partners/608423a9b126ac6ab3f8f0a5/anyPlacements/2e1f1f39-bad1-46a4-9488-c075dd95dc9b/impressions?apiKey=608423a104249fa8e9952323&sessionExternalId=3beb9714-82e9-4c08-938d-1391f5d86f2b&acceptContent=productIds,string' +``` + +## Responses + +### Impression + +Содержит данные для показа спонсорского содержимого. Может принимать разные формы, в зависимости от значения переданного в запросе `acceptContent`. + +- `StringImpression` соответствует `acceptContent=string` +- `ProductIdsImpression` соответствует `acceptContent=productIds` +- `BannersImpression` соответствует `acceptContent=banners` +- `SharedBannersImpression` соответствует `acceptContent=sharedBanners` + +### StringImpression + +| Имя поля | Обязательное | Тип | Описание | +| ------------- | ------------ | ----------------------- | -------------------------------------------------------- | +| `id` | Да | string | Идентификатор запрошенного показа | +| `contentType` | Нет | string | Тип содержимого. Всегда равен `string` | +| `content` | Да | StringImpressionContent | [Содержимое для показа](api-sponsorskikh-razmeshenii.md) | + +### StringImpressionContent + +Строковое содержимое для показа + +| Имя поля | Обязательное | Тип | Описание | +| -------- | ------------ | ------ | ------------------------- | +| `id` | Да | string | Идентификатор содержимого | +| `string` | Да | string | Произвольный текст | + +### Примеры + +Объект типа `Impression` с полем `content` типа «строка». + +```javascript +{ + "id": "impression identifier", + "contentType": "string", + "content": { + "id": "content identifier", + "string": "any string" + } +} +``` + +### ProductIdsImpression + +| Имя поля | Обязательное | Тип | Описание | +| ------------- | ------------ | --------------------------- | -------------------------------------------------------- | +| `id` | Да | string | Идентификатор запрошенного показа | +| `contentType` | Нет | string | Тип содержимого. Всегда равен `productIds` | +| `content` | Да | ProductIdsImpressionContent | [Содержимое для показа](api-sponsorskikh-razmeshenii.md) | + +### ProductIdsImpressionContent + +Cодержимое для показа товарной полки + +| Имя поля | Обязательное | Тип | Описание | +| ------------ | ------------ | ------------ | ---------------------------------------------- | +| `id` | Да | string | Идентификатор содержимого | +| `productIds` | Да | number array | Массив идентификаторов товаров для отображения | + +### Примеры + +Объект типа Impression с полем `content` типа «товарная полка». + +```javascript +{ + "id": "impression identifier", + "contentType": "productIds", + "content": { + "id": "content identifier", + "productIds": [123, 321] + } +} +``` + +### BannersImpression + +| Имя поля | Обязательное | Тип | Описание | +| ------------- | ------------ | ------------------------ | -------------------------------------------------------- | +| `id` | Да | string | Идентификатор запрошенного показа | +| `contentType` | Нет | string | Тип содержимого. Всегда равен `banners` | +| `content` | Да | BannersImpressionContent | [Содержимое для показа](api-sponsorskikh-razmeshenii.md) | + +### BannersImpressionContent + +Cодержимое для показа баннеров + +| Имя поля | Обязательное | Тип | Описание | +| --------- | ------------ | ------------ | ------------------------------- | +| `id` | Да | string | Идентификатор содержимого | +| `banners` | Да | Banner array | Массив баннеров для отображения | + +### Banner + +Информация о баннере + +| Имя поля | Обязательное | Тип | Описание | +| ------------ | ------------ | ------ | ------------------------------------ | +| `targetUrl` | Нет | string | URL для перехода при клике на баннер | +| `pictureUrl` | Да | string | URL изображения | + +### Примеры + +Объект типа Impression с полем `content` типа «баннеры». + +```javascript +{ + "id": "impression identifier", + "contentType": "banners", + "content": { + "id": "content identifier", + "banners": [ + { + "targetUrl" : "http://host/path", + "pictureUrl": "http://host/path/image.png" + }, + { + "targetUrl" : "http://host/path", + "pictureUrl": "http://host/path/image.png" + }, + ] + } +} +``` + +### SharedBannersImpression + +Содержимое для показа общих баннеров. Отличается от BannersImpression тем, что тут могут присутствовать баннеры разных рекламодателей. + +| Имя поля | Обязательное | Тип | Описание | +| ------------- | ------------ | ----------------------------- | -------------------------------------------------------- | +| `id` | Да | string | Идентификатор запрошенного показа | +| `contentType` | Нет | string | Тип содержимого. Всегда равен `sharedBanners` | +| `content` | Да | BannerImpressionContent array | [Содержимое для показа](api-sponsorskikh-razmeshenii.md) | + +### BannerImpressionContent + +Cодержимое для показа баннера + +| Имя поля | Обязательное | Тип | Описание | +| -------- | ------------ | ------ | ------------------------- | +| `id` | Да | string | Идентификатор содержимого | +| `banner` | Да | Banner | Баннер для отображения | + +### Примеры + +Объект типа Impression с полем `content` типа «общие баннеры». + +```javascript +{ + "id": "impression identifier", + "contentType": "sharedBanners", + "content": [ + { + "id": "content identifier", + "banner": { + "targetUrl" : "http://host/path", + "pictureUrl": "http://host/path/image.png" + } + }, + { + "id": "content identifier", + "banner": { + "targetUrl" : "http://host/path", + "pictureUrl": "http://host/path/image.png" + } + } + ] +} +``` + +## Status codes + +| Код ответа | Название | Описание | +| ---------- | --------------- | --------------------------------------------------------------------------- | +| 200 | OK | Запрос принят | +| 204 | NoContent | По запросу ничего не найдено | +| 400 | BadRequest | Ошибка в запросе, необходимо проверить правильность построения запроса | +| 401 | Unauthorized | Ошибка авторизации, необходимо проверить корректность `partnerId`, `apiKey` | +| 403 | Forbidden | Доступ запрещен | +| 404 | NotFound | Запрошенный ресурс не найден, необходимо проверить правильность URL | +| 429 | TooManyRequests | Превышение лимита запросов | + +## Время ответа + +Ожидаемое время ответа – 100 мс для всех ресурсов (может отличаться из-за особенностей сетевой инфраструктуры). + +## Ограничения + +По умолчанию действует ограничение в 50 запросов/секунду для каждой рекламной площадки. При необходимости возможно изменить (с помощью аккаунт-менеджера). diff --git a/integraciya-s-retail-rocket/http-tracking-api.md b/integraciya-s-retail-rocket/http-tracking-api.md new file mode 100644 index 0000000..a7b1d0d --- /dev/null +++ b/integraciya-s-retail-rocket/http-tracking-api.md @@ -0,0 +1,1066 @@ +# API трекинг пользовательского поведения + +Данные о пользовательском поведении необходимы для работы многих продуктов Retail Rocket: товарных рекомендаций, автоматизированных коммуникационных кампаний, для отслеживания метрик эффективности коммуникаций и т.д. + +## **Общие концепции** + +Для передачи пользовательского поведения в систему Retail Rocket необходимо вызывать соответствующие действию методы трекинг API для всех значимых действий пользователя (просмотр товара, добавление в корзину и т.д.). Ниже описаны методы для каждого такого действия с их параметрами, возможными кодами ответов и примерами вызова. + +## **Base URL** + +`https://apptracking.retailrocket.net/1.0/` + +## Resources + +Трекинг API придерживается [общих принципов интеграционных API](obshie-principy-integracii-s-retail-rocket.md). + +### Просмотр карточки товара + +Должен быть вызван при каждом просмотре посетителем карточки товара. + +**Path** + +**`view`** + +**HTTP-метод** + +`POST` + +**Параметры строки запроса** + +| Имя параметра | Обязательное | Тип | Описание | +| ------------- | ------------ | ------ | ---------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | + +**HTTP-заголовки** + +`Content-type: application/json` + +**Тело запроса** + +В теле запроса передается объект типа **`ViewEvent`** со следующими полями: + +| Имя поля | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#upravlenie-sessiei) | +| `productId` | Да | integer | [Идентификатор товара](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#svedeniya-o-tovare) | +| `stockId` | Нет | string | [Идентификатор склада, к которому принадлежит товар](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#svedeniya-o-tovare) | +| `timestamp` | Да | string | [Метка времени вызова](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#metka-vremeni-vyzova) | + +**Пример вызова** + +```bash +curl \ + -X POST "https://apptracking.retailrocket.net/1.0/view?apiKey=608423a104249fa8e9952323&partnerId=608423a9b126ac6ab3f8f0a5" \ + -H "Content-type: application/json" \ + --data " + { + \"sessionExternalId\": \"60842392e4881c65e6c5e423\", + \"productId\": 123456, + \"stockId\": \"NewYork\", + \"timestamp\": \"2018-09-15T15:53:00+00:00\" + } + " +``` + +### Просмотр карточки группового товара + +Должен быть вызван при каждом просмотре посетителем карточки товара, на которой представлен групповой товар. + +#### Path + +**`groupView`** + +#### HTTP-метод + +`POST` + +#### Параметры строки запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------- | ------------ | ------ | ---------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | + +#### HTTP-заголовки + +`Content-type: application/json` + +#### Тело запроса + +В теле запроса передается объект типа **`GroupViewEvent`** со следующими полями: + +| Имя поля | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#upravlenie-sessiei) | +| `groupId` | Да | integer | [Идентификатор товарной группы](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#svedeniya-o-tovare) | +| `productIds` | Да | number array | [Список идентификаторов товаров](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#svedeniya-o-tovare) | +| `stockId` | Нет | string | [Идентификатор склада, к которому принадлежит товар](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#svedeniya-o-tovare) | +| `timestamp` | Да | string | [Метка времени вызова](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#metka-vremeni-vyzova) | + +#### Пример вызова + +```bash +curl \ + -X POST "https://apptracking.retailrocket.net/1.0/groupView?apiKey=608423a104249fa8e9952323&partnerId=608423a9b126ac6ab3f8f0a5" \ + -H "Content-type: application/json" \ + --data " + { + \"sessionExternalId\": \"60842392e4881c65e6c5e423\", + \"groupId\": 654321, + \"productIds\": [123456, 234567, 345678], + \"stockId\": \"NewYork\", + \"timestamp\": \"2018-09-15T15:53:00+00:00\" + } + " +``` + +### Добавление товара в корзину + +Должен быть вызван при каждом добавлении посетителем товара в корзину. + +**Path** + +**`addToBasket`** + +**HTTP-метод** + +`POST` + +**Параметры строки запроса** + +| Имя параметра | Обязательное | Тип | Описание | +| ------------- | ------------ | ------ | ---------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | + +**HTTP-заголовки** + +`Content-type: application/json` + +**Тело запроса** + +В теле запроса передается объект типа **`AddToBasketEvent`** со следующими полями: + +| Имя поля | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#upravlenie-sessiei) | +| `productId` | Да | integer | [Идентификатор товара](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#svedeniya-o-tovare) | +| `stockId` | Нет | string | [Идентификатор склада, к которому принадлежит товар](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#svedeniya-o-tovare) | +| `timestamp` | Да | string | [Метка времени вызова](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#metka-vremeni-vyzova) | + +#### Пример вызова + +```bash +curl \ + -X POST "https://apptracking.retailrocket.net/1.0/addToBasket?apiKey=608423a104249fa8e9952323&partnerId=608423a9b126ac6ab3f8f0a5" \ + -H "Content-type: application/json" \ + --data " + { + \"sessionExternalId\": \"60842392e4881c65e6c5e423\", + \"productId\": 123456, + \"stockId\": \"NewYork\", + \"timestamp\": \"2018-09-15T15:53:00+00:00\" + } + " +``` + +### Просмотр страницы товарной категории + +Должен быть вызван при просмотре посетителем страницы товарной категории. + +{% hint style="warning" %} +В зависимости от того как выполнена интеграция передачи [товарной базы](../#tovarnaya-baza), необходимо вызывать разные методы для передачи факта просмотра пользователем страницы товарной категории. + +[Интеграции через YML-файл](http-tracking-api.md#pri-integracii-cherez-yml-fail) + +[Интеграции через Product API](http-tracking-api.md#pri-integracii-cherez-product-api) +{% endhint %} + +#### При интеграции через YML-файл + +В YML файле доступно дерево категорий с целочисленными идентификаторами категории, поэтому и товары имеют целочисленные идентификаторы категорий, что позволяет использовать такие идентификаторы в трекинге пользовательского поведения. + +**Path** + +**`categoryView`** + +**HTTP-метод** + +`POST` + +**Параметры строки запроса** + +| Имя параметра | Обязательное | Тип | Описание | +| ------------- | ------------ | ------ | ---------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | + +**HTTP-заголовки** + +`Content-type: application/json` + +**Тело запроса** + +В теле запроса передается объект типа **`CategoryViewEvent`** со следующими полями: + +| Имя поля | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#upravlenie-sessiei) | +| `categoryId` | Да | integer | [Идентификатор категории товара](obshie-principy-integracii-s-retail-rocket.md#sposoby-peredachi-tovarnoi-bazy) | +| `timestamp` | Да | string | [Метка времени вызова](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#metka-vremeni-vyzova) | + +Пример вызова + +```bash +curl \ + -X POST "https://apptracking.retailrocket.net/1.0/categoryView?apiKey=608423a104249fa8e9952323&partnerId=608423a9b126ac6ab3f8f0a5" \ + -H "Content-type: application/json" \ + --data " + { + \"sessionExternalId\": \"60842392e4881c65e6c5e423\", + \"categoryId\": 123456, + \"timestamp\": \"2018-09-15T15:53:00+00:00\" + } + " +``` + +#### При интеграции через Product API + +При использовании product API категория передается как `categoryPath` также она должна быть передана и при просмотре страницы категории. + +#### Path + +**`categoryViewByCategoryPath`** + +#### HTTP-метод + +`POST` + +#### Параметры строки запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------- | ------------ | ------ | ---------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | + +#### HTTP-заголовки + +`Content-type: application/json` + +#### Тело запроса + +В теле запроса передается объект типа **`CategoryViewEvent`** со следующими полями: + +| Имя поля | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#upravlenie-sessiei) | +| `categoryPath` | Да | string | [Путь категории товара](obshie-principy-integracii-s-retail-rocket.md#sposoby-peredachi-tovarnoi-bazy) | +| `timestamp` | Да | string | [Метка времени вызова](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#metka-vremeni-vyzova) | + +#### Пример вызова + +```bash +curl \ + -X POST "https://apptracking.retailrocket.net/1.0/categoryViewByCategoryPath?apiKey=608423a104249fa8e9952323&partnerId=608423a9b126ac6ab3f8f0a5" \ + -H "Content-type: application/json" \ + --data " + { + \"sessionExternalId\": \"60842392e4881c65e6c5e423\", + \"categoryPath\": \"Товары для дома/Кухня/Вилки\", + \"timestamp\": \"2018-09-15T15:53:00+00:00\" + } + " +``` + +### Заказ товара + +​Должен быть вызван для каждой товарной позиции в заказе. + +#### Path + +**`order`** + +#### HTTP-метод + +`POST` + +#### Параметры строки запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------- | ------------ | ------ | ---------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | + +#### HTTP-заголовки + +`Content-type: application/json` + +#### Тело запроса + +В теле запроса передается объект типа **`OrderEvent`** со следующими полями: + +| Имя поля | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#upravlenie-sessiei) | +| `productId` | Да | integer | [Идентификатор товара](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#svedeniya-o-tovare) | +| `stockId` | Нет | string | [Идентификатор склада, к которому принадлежит товар](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#svedeniya-o-tovare) | +| `price` | Да | number | Цена с учетом скидок за **единицу товара** | +| `quantity` | Да | number | Кол-во единиц товара в заказе | +| `transaction` | Да | string | Идентификатор покупки | +| `timestamp` | Да | string | [Метка времени вызова](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#metka-vremeni-vyzova) | + +#### Пример вызова + +```bash +curl \ + -X POST "https://apptracking.retailrocket.net/1.0/order?apiKey=608423a104249fa8e9952323&partnerId=608423a9b126ac6ab3f8f0a5" \ + -H "Content-type: application/json" \ + --data " + { + \"sessionExternalId\": \"60842392e4881c65e6c5e423\", + \"productId\": 123456, + \"stockId\": \"NewYork\", + \"quantity\": 2, + \"price\": 234, + \"transaction\": \"135243\", + \"timestamp\": \"2018-09-15T15:53:00+00:00\" + } + " +``` + +### Поисковый запрос + +Должен быть вызван при вводе посетителем поисковой фразы. + +#### Path + +**`search`** + +#### HTTP-метод + +`POST` + +#### Параметры строки запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------- | ------------ | ------ | ---------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | + +#### HTTP-заголовки + +`Content-type: application/json` + +#### Тело запроса + +В теле запроса передается объект типа **`SearchEvent`** со следующими полями: + +| Имя поля | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#upravlenie-sessiei) | +| `searchPhrase` | Да | string | Поисковая фраза, которую ввел пользователь | +| `stockId` | Нет | string | [Идентификатор склада, к которому принадлежит пользователь](obshie-principy-integracii-s-retail-rocket.md#podderzhka-regionalnosti-sklad-region) | +| `timestamp` | Да | string | [Метка времени вызова](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#metka-vremeni-vyzova) | + +#### Пример вызова + +```bash +curl \ + -X POST "https://apptracking.retailrocket.net/1.0/search?apiKey=608423a104249fa8e9952323&partnerId=608423a9b126ac6ab3f8f0a5" \ + -H "Content-type: application/json" \ + --data " + { + \"sessionExternalId\": \"60842392e4881c65e6c5e423\", + \"searchPhrase\": \"подгузник для новорожденных\", + \"stockId\": \"NewYork\", + \"timestamp\": \"2018-09-15T15:53:00+00:00\" + } + " +``` + +### **Аутентификация** пользователя + +Для того, чтобы пользовательское поведение было правильно учтено для [контакта](../#kontakt), в момент, когда становится известен идентификатор посетителя(логин на сайте), необходимо передать устойчивый идентификатор посетителя в систему Retail Rocket. + +{% hint style="info" %} +**`contactExternalId` -** уникальный идентификатор контакта, по которому пользователь может быть распознан в системе клиента. Служит для обмена информацией о контактах между платформой Retail Rocket и источниками данных клиента. +{% endhint %} + +{% hint style="warning" %} +**`phone -`** Номер телефона пользователя следует передавать в формате E.164 +{% endhint %} + +#### Требования к contactExternalId + +* Должен состоять только из цифр и букв; +* Не превышать 50 символов; + +#### Path + +**`setContact`** + +#### HTTP-метод + +`POST` + +#### HTTP-заголовки + +`Content-type: application/json` + +#### Параметры строки запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------- | ------------ | ------ | ---------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | + +#### Тело запроса + +| Имя поля | Обязательное | Тип | Описание | +| ------------------- | ------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#upravlenie-sessiei) | +| `contactExternalId` | Да | string | [Уникальный идентификатор контакта](http-tracking-api.md#ustanovka-sessii) | +| `timestamp` | Да | string | [Метка времени вызова](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#metka-vremeni-vyzova) | +| `email` | Нет | string | Адрес почты пользователя | +| `stockId` | Нет | string | [Идентификатор склада, к которому принадлежит пользователь](obshie-principy-integracii-s-retail-rocket.md#podderzhka-regionalnosti-sklad-region) | +| `phone` | Нет | string | [Номер телефона пользователя](http-tracking-api.md#autentifikaciya-polzovatelya) | +| `customData` | Нет | JSON Object | Пользовательские параметры | + +#### Пример вызова + +```bash +curl \ + -X POST "https://apptracking.retailrocket.net/1.0/setContact?apiKey=608423a104249fa8e9952323&partnerId=608423a9b126ac6ab3f8f0a5" \ + -H "Content-type: application/json" \ + --data " + { + \"sessionExternalId\": \"60842392e4881c65e6c5e423\", + \"contactExternalId\": \"2342dfgf253454c645346wer3\", + \"stockId\": \"NewYork\", + \"timestamp\": \"2018-09-15T15:53:00+00:00\", + \"email\": \"example@email.com\" + } + " +``` + +### Запуск сценария 'Welcome Sequence' + +Запускает цепочку email-сценария WelcomeSequence. + +{% hint style="info" %} +**Welcome-цепочка** — это приветственное письмо или серия писем, в которых интернет-магазин рассказывает о своем бренде, или об особенностях своей работы. +{% endhint %} + +{% hint style="warning" %} +На момент вызова метода, email-адрес должен быть в базе подписчиков партнера. +{% endhint %} + +#### Path + +**`welcomeSequence`** + +#### HTTP-метод + +`POST` + +#### Параметры строки запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------- | ------------ | ------ | ---------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | + +#### HTTP-заголовки + +`Content-type: application/json` + +#### Тело запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#upravlenie-sessiei) | +| `timestamp` | Да | string | [Метка времени вызова](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#metka-vremeni-vyzova) | +| `email` | Да | string | Адрес почты пользователя | + +#### Пример вызова + +```bash +curl \ + -X POST "https://apptracking.retailrocket.net/1.0/welcomeSequence?apiKey=608423a104249fa8e9952323&partnerId=608423a9b126ac6ab3f8f0a5" \ + -H "Content-type: application/json" \ + --data " + { + \"sessionExternalId\": \"60842392e4881c65e6c5e423\", + \"email\": \"example@gmail.com\", + \"timestamp\": \"2018-09-15T15:53:00+00:00\" + } + " +``` + +### Клик по содержимому письма + +Событие клика по содержимому письма. Должно вызываться, если пользователь переходит из письма. + +{% hint style="info" %} +Все ссылки в письме содержат GET параметр **`MailTrackingId`** с уникальным значением для каждого письма. При каждом переходе из письма на сайт, URL страницы будет содержать параметр **`MailTrackingId`**, значение которого следует передавать в тело запроса. +{% endhint %} + +#### Path + +**`emailClick`** + +#### HTTP-метод + +`POST` + +#### Параметры строки запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------- | ------------ | ------ | ---------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | + +#### HTTP-заголовки + +`Content-type: application/json` + +#### Тело запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------------- | ------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#upravlenie-sessiei) | +| `timestamp` | Да | string | [Метка времени вызова](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#metka-vremeni-vyzova) | +| `mailTrackingId` | Да | string | [Метка пользователя из письма](http-tracking-api.md#zapusk-scenariya-welcome-sequence-1) | +| `customData` | Нет | JSON объект | Пользовательские параметры | + +#### Пример вызова + +```bash +curl \ + -X POST "https://apptracking.retailrocket.net/1.0/emailClick?apiKey=608423a104249fa8e9952323&partnerId=608423a9b126ac6ab3f8f0a5" \ + -H "Content-type: application/json" \ + --data " + { + \"sessionExternalId\": \"60842392e4881c65e6c5e423\", + \"mailTrackingId\": \"5b488f277ecc191c98859541\", + \"timestamp\": \"2018-09-15T15:53:00+00:00\" + } + " +``` + +## Передача данных о взаимодействии с рекомендациями + +Для оценки эффективности рекомендаций, а также для учета продаж через товарные рекомендации, необходимо передавать соответствующие события взаимодействия с рекомендациями. + +{% hint style="info" %} +Идентификатор блока рекомендаций `recomBlockId` **-** любая строка до 50 символов, используется для идентификации каждого блока рекомендаций +{% endhint %} + +### Просмотр блока рекомендаций + +Должен быть вызван при каждом показе блока рекомендаций пользователю приложения + +**Path** + +**`recomBlockViewed`** + +**HTTP-метод** + +`POST` + +**Параметры строки запроса** + +| Имя параметра | Обязательное | Тип | Описание | +| ------------- | ------------ | ------ | ---------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | + +**HTTP-заголовки** + +`Content-type: application/json` + +**Тело запроса** + +| Имя поля | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#upravlenie-sessiei) | +| `recomBlockId` | Да | string | [Идентификатор блока рекомендаций](http-tracking-api.md#peredacha-dannykh-o-vzaimodeistvii-s-rekomendaciyami) | +| `timestamp` | Да | string | [Метка времени вызова](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#metka-vremeni-vyzova) | + +#### Пример вызова + +```bash +curl \ + -X POST "https://apptracking.retailrocket.net/1.0/recomBlockViewed?apiKey=608423a104249fa8e9952323&partnerId=608423a9b126ac6ab3f8f0a5" \ + -H "Content-type: application/json" \ + --data " + { + \"sessionExternalId\": \"60842392e4881c65e6c5e423\", + \"recomBlockId\": \"568da4f6-7952-49b1-afd3-9ac44d6e78c7\", + \"timestamp\": \"2018-09-15T15:53:00+00:00\" + } + " +``` + +### Клик по блоку рекомендаций + +Нажатие по рекомендации – это, фактически, переход в карточку товара, рекомендованную в блоке. Элементы, такие как название товара, изображения товара, цена и другие, относящиеся к рекомендуемому товару из рекомендаций, должны содержать обработчик tap и вызывать событие recomTap. + +#### Path + +**`recomTap`** + +#### HTTP-метод + +`POST` + +#### Параметры строки запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------- | ------------ | ------ | ---------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | + +#### HTTP-заголовки + +`Content-type: application/json` + +#### Тело запроса + +| Имя поля | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#upravlenie-sessiei) | +| `productId` | Да | integer | [Идентификатор товара](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#svedeniya-o-tovare) | +| `stockId` | Нет | string | [Идентификатор склада, к которому принадлежит товар](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#svedeniya-o-tovare) | +| `timestamp` | Да | string | [Метка времени вызова](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#metka-vremeni-vyzova) | +| `recomBlockId` | Да | string | [Идентификатор блока рекомендаций](http-tracking-api.md#peredacha-dannykh-o-vzaimodeistvii-s-rekomendaciyami) | + +#### Пример вызова + +```bash +curl \ + -X POST "https://apptracking.retailrocket.net/1.0/recomTap?apiKey=608423a104249fa8e9952323&partnerId=608423a9b126ac6ab3f8f0a5" \ + -H "Content-type: application/json" \ + --data " + { + \"sessionExternalId\": \"60842392e4881c65e6c5e423\", + \"productId\": 123456, + \"stockId\": \"NewYork\", + \"timestamp\": \"2018-09-15T15:53:00+00:00\", + \"recomBlockId\": \"5994d90bc7d0114fa0a26122\" + } + " +``` + +### Добавление в корзину из блока рекомендаций + +Если в блоке товарных рекомендаций используется кнопка добавления товара в корзину, то при каждом добавлении товара в корзину из блока рекомендаций (без перехода в карточку товара) необходимо вызывать обработчик добавления товара из блока в корзину. + +#### **Path** + +**`recomAddToBasket`** + +#### HTTP-метод + +`POST` + +#### HTTP-заголовки + +`Content-type: application/json` + +#### Параметры строки запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------- | ------------ | ------ | ---------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | + +#### Тело запроса + +| Имя поля | Обязательное | Тип | Описание | +| ------------------- | ------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#upravlenie-sessiei) | +| `productId` | Да | integer | [Идентификатор товара](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#svedeniya-o-tovare) | +| `stockId` | Нет | string | [Идентификатор склада, к которому принадлежит товар](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#svedeniya-o-tovare) | +| `timestamp` | Да | string | [Метка времени вызова](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#metka-vremeni-vyzova) | +| `recomBlockId` | Да | string | [Идентификатор блока рекомендаций](http-tracking-api.md#peredacha-dannykh-o-vzaimodeistvii-s-rekomendaciyami) | + +#### Пример вызова + +```bash +curl \ + -X POST "https://apptracking.retailrocket.net/1.0/recomAddToBasket?apiKey=608423a104249fa8e9952323&partnerId=608423a9b126ac6ab3f8f0a5" \ + -H "Content-type: application/json" \ + --data " + { + \"sessionExternalId\": \"60842392e4881c65e6c5e423\", + \"productId\": 123456, + \"stockId\": \"NewYork\", + \"timestamp\": \"2018-09-15T15:53:00+00:00\", + \"recomBlockId\": \"5994d90bc7d0114fa0a26122\" + } + " +``` + +## Передача данных о взаимодействии со спонсорским контентом + +### Просмотр спонсорского контента + +Должен быть вызван при каждом показе посетителю спонсорского контента. + +#### Path + +**`impressionContentViewed`** + +#### HTTP-метод + +`POST` + +#### Параметры строки запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------- | ------------ | ------ | ---------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | + +#### HTTP-заголовки + +`Content-type: application/json` + +#### Тело запроса + +В теле запроса передается объект типа **`ImpressionContentViewedEvent`** со следующими полями: + +| Имя поля | Обязательное | Тип | Описание | +| --------------------- | ------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#upravlenie-sessiei) | +| `impressionContentId` | Да | string | [Идентификатор спонсорского контента](instrukciya-po-integracii-retail-rocket-sponsorskoe-razmeshenie.md#integraciya-sistem) | +| `timestamp` | Да | string | [Метка времени вызова](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#metka-vremeni-vyzova) | + +#### Пример вызова + +```bash +curl \ + -X POST "https://apptracking.retailrocket.net/1.0/impressionContentViewed?apiKey=608423a104249fa8e9952323&partnerId=608423a9b126ac6ab3f8f0a5" \ + -H "Content-type: application/json" \ + --data " + { + \"sessionExternalId\": \"60842392e4881c65e6c5e423\", + \"impressionContentId\": \"568da4f6-7952-49b1-afd3-9ac44d6e78c7\", + \"timestamp\": \"2018-09-15T15:53:00+00:00\" + } + " +``` + +### Клик по спонсорскому контенту + +Должен быть вызван при каждом клике посетителем в спонсорский контент. + +#### Path + +**impressionContentClicked** + +#### HTTP-метод + +`POST` + +#### Параметры строки запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------- | ------------ | ------ | ---------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | + +#### HTTP-заголовки + +`Content-type: application/json` + +#### Тело запроса + +В теле запроса передается объект типа **`ImpressionContentViewedEvent`** со следующими полями: + +| Имя поля | Обязательное | Тип | Описание | +| --------------------- | ------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `sessionExternalId` | Да | string | [Идентификатор пользователя](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#upravlenie-sessiei) | +| `impressionContentId` | Да | string | [Идентификатор спонсорского контента](instrukciya-po-integracii-retail-rocket-sponsorskoe-razmeshenie.md#integraciya-sistem) | +| `timestamp` | Да | string | [Метка времени вызова](https://docs.retailrocket.net/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket#metka-vremeni-vyzova) | + +#### Пример вызова + +```bash +curl \ + -X POST "https://apptracking.retailrocket.net/1.0/impressionContentClicked?apiKey=608423a104249fa8e9952323&partnerId=608423a9b126ac6ab3f8f0a5" \ + -H "Content-type: application/json" \ + --data " + { + \"sessionExternalId\": \"60842392e4881c65e6c5e423\", + \"impressionContentId\": \"568da4f6-7952-49b1-afd3-9ac44d6e78c7\", + \"timestamp\": \"2018-09-15T15:53:00+00:00\" + } + " +``` + +## Пакетная загрузка пользовательского поведения + +API предоставляет возможность пакетной загрузки пользовательского поведения. В теле вызова метода передается список пользовательских событий. Вызов гарантирует сохранение порядка переданных в него событий. + +### Специфика использования пакетной загрузки + +Метод API `visitorEvents` решает проблему сохранения порядка пользовательских событий. К примеру, при потере соединения с сетью интернет, когда нельзя передать события в режиме реального времени, но действия совершаются в приложении. Как только у приложения появится доступ к сети интернет, нам важно получить эти события, но если отправить их с помощью обычных вызовов `view`, `addToBasket` - есть вероятность потерять порядок, из-за того, что каждый из вызовов `view`, `addToBasket` обработается разным сервером. Для сохранения порядка действий есть метод `visitorEvents`, принимающий набор событий и гарантирующий, что события будут сохранены в том порядке в котором они переданы. + +### Особенности использования + +{% hint style="danger" %} +Для отправки двух пакетов событий, содержащих разное поведение одного пользователя, нужно отправить первый, дождаться успешного статуса ответа и после этого отправить второй; +{% endhint %} + +{% hint style="danger" %} +Нельзя параллельно совершать более одного вызова, в которых есть события по одному пользователю - это может нарушить порядок; +{% endhint %} + +{% hint style="warning" %} +Из-за необходимости вернуть подтверждение сохранения событий и порядка время ответа **`visitorEvents`**, как правило, на порядки больше времени ответа обычных (не пакетных) вызовов трекинга и может составлять порядка 1.5 секунд и более. В связи с этим не следует использовать данный вызов для передачи realtime-событий; +{% endhint %} + +{% hint style="info" %} +В вызове можно передать события для разных пользователей (**sessionExternalId**); +{% endhint %} + +{% hint style="info" %} +Можно параллельно вызывать **`visitorEvents`** с пакетами для разных пользователей, т.к. порядок важен только в рамках одного пользователя; +{% endhint %} + +#### Path + +**`visitorEvents`** + +#### HTTP-метод + +`POST` + +#### Параметры строки запроса + +| Имя параметра | Обязательное | Тип | Описание | +| ------------- | ------------ | ------ | ---------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Да | string | [Ключ авторизации](obshie-principy-integracii-s-retail-rocket.md#avtorizaciya) | +| `partnerId` | Да | string | [Идентификатор интернет-магазина](obshie-principy-integracii-s-retail-rocket.md#identifikator-internet-magazina) | + +#### HTTP-заголовки + +`Content-type: application/json` + +#### Тело запроса + +В теле запроса передается список пользовательских событий любого из следующих типов: + +**`ViewEventEnvelope`** + +| Имя поля | Обязательное | Тип | Описание | +| -------- | ------------ | ----------- | --------------------------------------------------------------------------------------- | +| `view` | Да | `ViewEvent` | Тип подробно описан в разделе «Просмотр карточки товара» как тип параметра тела запроса | + +**`GroupEventViewEnvelope`** + +| Имя поля | Обязательное | Тип | Описание | +| ----------- | ------------ | ---------------- | -------------------------------------------------------------------------------------------------- | +| `groupView` | Да | `GroupViewEvent` | Тип подробно описан в разделе «Просмотр карточки группового товара» как тип параметра тела запроса | + +**`AddToBasketEventEnvelope`** + +| Имя поля | Обязательное | Тип | Описание | +| ------------- | ------------ | ------------------ | ------------------------------------------------------------------------------------------ | +| `addToBasket` | Да | `addToBasketEvent` | Тип подробно описан в разделе «Добавление товара в корзину» как тип параметра тела запроса | + +**`OrderEventEnvelope`** + +| Имя поля | Обязательное | Тип | Описание | +| -------- | ------------ | ------------ | --------------------------------------------------------------------------- | +| `order` | Да | `OrderEvent` | Тип подробно описан в разделе «Заказ товара» как тип параметра тела запроса | + +**`CategoryViewEventEnvelope`** + +| Имя поля | Обязательное | Тип | Описание | +| -------------- | ------------ | ------------------- | ------------------------------------------------------------------------------------------------- | +| `categoryView` | Да | `CategoryViewEvent` | Тип подробно описан в разделе «Просмотр страницы категории товара» как тип параметра тела запроса | + +**`SearchViewEventEnvelope`** + +| Имя поля | Обязательное | Тип | Описание | +| -------- | ------------ | ----------------- | ------------------------------------------------------------------------------------------------- | +| `search` | Да | `SearchViewEvent` | Тип подробно описан в разделе «Просмотр страницы категории товара» как тип параметра тела запроса | + +**`ImpressionContentViewedEventEnvelope`** + +| Имя поля | Обязательное | Тип | Описание | +| ------------------------- | ------------ | ------------------------------ | --------------------------------------------------------------------------------------------- | +| `impressionContentViewed` | Да | `ImpressionContentViewedEvent` | Тип подробно описан в разделе «Просмотр спонсорского контента» как тип параметра тела запроса | + +**`ImpressionContentClickedEventEnvelope`** + +| Имя поля | Обязательное | Тип | Описание | +| -------------------------- | ------------ | ------------------------------- | -------------------------------------------------------------------------------------------- | +| `impressionContentClicked` | Да | `ImpressionContentClickedEvent` | Тип подробно описан в разделе «Клик по спонсорскому контенту» как тип параметра тела запроса | + +**`EmailClickEventEnvelope`** + +| Имя поля | Обязательное | Тип | Описание | +| ------------ | ------------ | ----------------- | ----------------------------------------------------------------------------------------- | +| `emailClick` | Да | `EmailClickEvent` | Тип подробно описан в разделе «Клик по содержимому письма» как тип параметра тела запроса | + +**`WelcomeSequenceEventEnvelope`** + +| Имя поля | Обязательное | Тип | Описание | +| ----------------- | ------------ | ---------------------- | ------------------------------------------------------------------------------------------------- | +| `welcomeSequence` | Да | `WelcomeSequenceEvent` | Тип подробно описан в разделе «Запуск сценария 'Welcome Sequence'» как тип параметра тела запроса | + +**`SetContactEventEnvelope`** + +| Имя поля | Обязательное | Тип | Описание | +| ------------ | ------------ | ----------------- | ------------------------------------------------------------------------------------------ | +| `setContact` | Да | `SetContactEvent` | Тип подробно описан в разделе «Аутентификация пользователя» как тип параметра тела запроса | + +**Пример вызова** + +{% tabs %} +{% tab title="Bash" %} +```bash +curl \ + -X POST "https://apptracking.retailrocket.net/1.0/visitorEvents?apiKey=608423a104249fa8e9952323&partnerId=608423a9b126ac6ab3f8f0a5" \ + -H "Content-type: application/json" \ + --data " + [ + { + \"view\": { + \"sessionExternalId\": \"60842392e4881c65e6c5e423\", + \"productId\": 123456, + \"stockId\": \"NewYork\", + \"timestamp\": \"2018-09-15T15:53:00+00:00\" + } + }, + { + \"groupView\": { + \"sessionExternalId\": \"60842392e4881c65e6c5e423\", + \"groupId\": 654321, + \"productIds\": [123456, 234567, 345678], + \"stockId\": \"NewYork\", + \"timestamp\": \"2018-09-15T15:53:00+00:00\" + } + }, + { + \"addToBasket\": { + \"sessionExternalId\": \"60842392e4881c65e6c5e423\", + \"productId\": 234567, + \"stockId\": \"NewYork\", + \"timestamp\": \"2018-09-15T15:53:00+00:00\" + } + }, + { + \"order\": { + \"sessionExternalId\": \"60842392e4881c65e6c5e423\", + \"productId\": 234567, + \"stockId\": \"NewYork\", + \"quantity\": 3, + \"price\": 1321.43, + \"transaction\": \"135243\", + \"timestamp\": \"2018-09-15T15:53:00+00:00\" + } + }, + { + \"categoryView\": { + \"sessionExternalId\": \"60842392e4881c65e6c5e423\", + \"categoryId\": 123456, + \"timestamp\": \"2018-09-15T15:53:00+00:00\" + } + }, + { + \"search\": { + \"sessionExternalId\": \"60842392e4881c65e6c5e423\", + \"searchPhrase\": \"подгузник для новорожденных\", + \"timestamp\": \"2018-09-15T15:53:00+00:00\" + } + }, + { + \"recomBlockViewed\": { + \"sessionExternalId\": \"60842392e4881c65e6c5e423\", + \"recomBlockId\": \"34453dffg34534te565\", + \"timestamp\": \"2018-09-15T15:53:00+00:00\" + } + }, + { + \"recomTap\": { + \"sessionExternalId\": \"60842392e4881c65e6c5e423\", + \"recomBlockId\": \"34453dffg34534te55\", + \"productId\" : 123, + \"timestamp\": \"2018-09-15T15:53:00+00:00\" + } + }, + { + \"recomAddToBasket\": { + \"sessionExternalId\": \"60842392e4881c65e6c5e423\", + \"recomBlockId\": \"34453dffg34534te54\", + \"productId\" : 123, + \"timestamp\": \"2018-09-15T15:53:00+00:00\" + } + }, + { + \"impressionContentViewed\": { + \"sessionExternalId\": \"60842392e4881c65e6c5e423\", + \"impressionContentId\": \"568da4f6-7952-49b1-afd3-9ac44d6e78c7\", + \"timestamp\": \"2018-09-15T15:53:00+00:00\" + } + }, + { + \"impressionContentClicked\": { + \"sessionExternalId\": \"60842392e4881c65e6c5e423\", + \"impressionContentId\": \"568da4f6-7952-49b1-afd3-9ac44d6e78c7\", + \"timestamp\": \"2018-09-15T15:53:00+00:00\" + } + }, + { + \"emailClick\": { + \"sessionExternalId\": \"60842392e4881c65e6c5e423\", + \"mailTrackingId\": \"5b488f277ecc191c98859541\", + \"timestamp\": \"2018-09-15T15:53:00+00:00\" + } + }, + { + \"setContact\": { + \"sessionExternalId\": \"60842392e4881c65e6c5e423\", + \"contactExternalId\": \"2342dfgf253454c645346wer3\", + \"email\": \"example@gmail.com\", + \"stockId\": \"Moscow\", + \"timestamp\": \"2018-09-15T15:53:00+00:00\" + } + }, + { + \"welcomeSequence\": { + \"sessionExternalId\": \"60842392e4881c65e6c5e423\", + \"email\": \"example@gmail.com\", + \"timestamp\": \"2018-09-15T15:53:00+00:00\" + } + } + ] +" +``` +{% endtab %} +{% endtabs %} + +## Коды ответов + +| Код ответа | Описание | +| ---------- | ---------------------------------------------------------------------- | +| 200 | Запрос принят | +| 400 | Ошибка в запросе, необходимо проверить правильность построения запроса | +| 401 | Ошибка аутентификации, проверьте корректность пары `apiKey` | +| 403 | Доступ запрещен | +| 404 | Запрошенный ресурс не найден, необходимо проверить правильность URL | + +## Время ответа + +Ожидаемое время ответа – 100 мс для всех ресурсов (может отличаться из-за особенностей сетевой инфраструктуры). + +## Ограничения + +По умолчанию действует ограничение в 100 запросов/секунду для площадки. При необходимости возможно изменить (с помощью аккаунт-менеджера). diff --git a/integraciya-s-retail-rocket/instrukciya-po-integracii-retail-rocket-sponsorskoe-razmeshenie.md b/integraciya-s-retail-rocket/instrukciya-po-integracii-retail-rocket-sponsorskoe-razmeshenie.md new file mode 100644 index 0000000..8bda493 --- /dev/null +++ b/integraciya-s-retail-rocket/instrukciya-po-integracii-retail-rocket-sponsorskoe-razmeshenie.md @@ -0,0 +1,72 @@ +# Инструкция по интеграции продукта «Спонсорские размещения» + +## Общие сведения + +Продукт «Спонсорские размещения» предназначен для показа товарных промо-материалов от производителей товаров (рекламодателей) на страницах интернет-магазина и сбора метрик взаимодействия посетителей с показанным контентом. + +Для того, чтобы эффективность показов контента была выше, система позволяет магазинам задавать контекст рекламного блока в зависимости от типа страницы, а рекламодателям дается возможность ограничивать показы контента в зависимости от данных, доступных на каждом типе страниц. + +#### Типы страниц: + +* Страница товарной карточки; +* Страница группы товаров (корзина, успешное завершение заказа); +* Страница товарной категории; +* Страница поисковой выдачи; +* Прочие страницы (главная, 404 и т.д.). + +Так на странице товарной карточки имеется возможность запросить контент, показ которого рекламодатель ограничил по товарным параметрам (цене товара, категории и т.д.); на поисковой странице – по семантическому ядру; на странице товарной категории – по товарной категории, которую просматривает пользователь. На всех страницах рекламодатель может ограничить показы в зависимости от профиля посетителя. + +Система позволяет магазину в рамках одного места на странице запрашивать различный контент для показа. + +#### Типы контента: + +* Товарная полка; +* Баннер; +* Строка; +* В дальнейшем планируется расширять варианты контента. + +Если в рамках одного размещения доступно более одного типа контента, рекламодатель может выбрать тот тип, который посчитает наиболее подходящим для кампании. + +## Этапы подключения системы к интернет-магазину + +### Составление карты интеграции + +Необходимо составить список страниц/экранов с местами, где планируется показывать спонсорский контент. Для каждого места получить идентификатор, выбрать тип страницы и тип контента. + +Должна получиться таблица (карта интеграции): + +| Место размещения | Идентификатор блока | Тип страницы | Тип контента | +| ---------------------------------- | ------------------------ | ----------------- | ---------------------- | +| Карточка товара до комментариев | 608d286f30e9b69fee2be370 | Товарная карточка | Товарная полка | +| Карточка товара после комментариев | 608d28c10f3b6f6091ae818c | Товарная карточка | Товарная полка, баннер | +| Поисковая страница | 608d2887b50326449cb41224 | Поисковая выдача | Баннер | +| Главная страница, баннерное место | 608d28f9b0a04d23b9aea5e5 | Прочее | Баннер | + +Карту интеграции составляет сотрудник Retail Rocket при участии сотрудников интернет-магазина. + +### Интеграция систем + +Интеграция состоит из двух этапов: интеграция спонсорских блоков, передача пользовательского поведения. + +#### Интеграция спонсорских блоков + +Имея на руках карту интеграции, программист интернет-магазина, используя документацию [API для получения спонсорских размещений](api-sponsorskikh-razmeshenii.md), запрашивает контент при каждом показе страницы, в зависимости от полученного [типа контента](instrukciya-po-integracii-retail-rocket-sponsorskoe-razmeshenie.md#tip-kontenta) обрабатывает ответ и встраивает в интерфейс интернет-магазина промо-материал. + +#### Передача пользовательского поведения + +Для системы Retail Rocket «Спонсорские размещения» пользовательское поведение необходимо в двух аспектах: учет взаимодействия пользователей со спонсорским контентом – расчет эффективности показов, и получение пользовательских событий для предоставления рекламодателем функционала таргетирования контента на основе профиля пользователя – таргетирование по интересам пользователя к категориям. + +**Передача взаимодействия посетителя интернет-магазина с спонсорским контентом** + +Просмотр промо-контента + +В случае успешного показа контента пользователю необходимо вызвать метод трекинга «[Просмотр спонсорского контента](http-tracking-api.md#prosmotr-sponsorskogo-kontenta)» и в качестве значения параметра «Идентификатор спонсорского контента» передать значение `impressionContentId`, полученное вместе с промо-контентом от Retail Rocket. + +Клик в промо-контент + +Если посетитель интернет-магазина кликнул в промо-контент, необходимо вызвать метод трекинга «[Клик по спонсорскому контенту](http-tracking-api.md#klik-po-sponsorskomu-kontentu)» и в качестве значения параметра «Идентификатор спонсорского контента» передать значение `impressionContentId`, полученное вместе с промо-контентом от Retail Rocket. + +**Передача пользовательского поведения на интернет-магазине** + +Методы трекинга пользовательского поведения описаны в разделе "[API трекинг пользовательского поведения](http-tracking-api.md)" + diff --git a/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket.md b/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket.md new file mode 100644 index 0000000..96980bb --- /dev/null +++ b/integraciya-s-retail-rocket/obshie-principy-integracii-s-retail-rocket.md @@ -0,0 +1,86 @@ +# Общие принципы интеграции с Retail Rocket + +## Основные принципы + +Все API Retail Rocket доступны по протоколу HTTP/2. + +Если для вызова метода требуется передача данных в теле запроса, то система ожидает их в формате JSON и соответствующего http-заголовка: `content-type: application/json` + +Все данные, которые возвращаются в результате вызова, возвращаются в формате JSON. + +Статусы HTTP-ответа имеют значение. Возможные статусы метода описываются в его документации. + +В целях оптимизации скорости подключения и передачи данных соединение следует кешировать. + +При отправке событий ответ ждать не нужно, исключение составляет лишь пакетная загрузка событий, детали которой описаны в [соответствующем разделе](http-tracking-api.md#specifika-ispolzovaniya-paketnoi-zagruzki). + +## **Идентификатор интернет-магазина** + +Для идентификации интернет-магазина в API используется параметр`partnerId`. Значение параметра выдается при регистрации в системе Retail Rocket и может быть получено либо запросом к аккаунт-менеджеру Retail Rocket, либо обращением в службу поддержки (support@retailrocket.ru), либо в [личном кабинете Retail Rocket](https://my.retailrocket.ru). + +{% hint style="info" %} +Значение является **публичным** и может быть использовано в открытом виде. +{% endhint %} + +## Авторизация + +Доступ к некоторым методам API ограничен, и для их использования требуется передавать параметр `apiKey`, значение которого можно получить у сотрудника Retail Rocket. + +{% hint style="danger" %} +Значение `apiKey` является **секретным** и не должно передаваться третьим лицам. +{% endhint %} + +{% hint style="danger" %} +Значение `apiKey` не должно передаваться или храниться на клиентской стороне (на сайте или в мобильном приложении). +{% endhint %} + +{% hint style="warning" %} +В случае утечки значения `apiKey`следует запросить у аккаунт-менеджера новое. Старое значение перестанет действовать. +{% endhint %} + +{% hint style="info" %} +**Рекомендация** + +Хранить значение `apiKey` в хранилище, в котором его можно изменить без необходимости выпускать новую версию сайта/приложения. +{% endhint %} + +## **Управление сессией** + +Для некоторых вызовов API требуется идентифицировать посетителя, для которого этот запрос применим. Для этого требуется передавать идентификатор пользовательской сессии в параметре `sessionExternalId.` Идентификатор должен быть сгенерирован на стороне магазина и обладать следующими свойствами: + +* Состоять только из цифр и букв; +* Не превышать 50 символов; +* Быть уникальным для устройства/браузера; +* Не содержать персональных данных, например, телефона или адреса электронной почты; +* Не должен изменяться при авторизации или смене аккаунта. + +{% hint style="info" %} +**Рекомендация** + +При первом появлении посетителя на сайте или в мобильном приложении генерировать GUID и использовать его в качестве `sessionExternalId` для последующих вызовов API. +{% endhint %} + +## Метка времени вызова + +Для корректной работы многих продуктов Retail Rocket необходимо знать время, когда метод был вызван, для этого в некоторых методах API предусмотрен опциональный параметр `timestamp`, в значении которого система Retail Rocket ожидает дату и время в формате ISO 8601. + +Если опциональный параметр не задан, то в качестве временной метки будет использовано серверное время Retail Rocket на момент вызова. + +## Сведения о товаре + +Если в методе API требуются товарные данные (например, идентификатор товара/склада и т.д.), значение таких параметров должно совпадать со значениями, переданными с товарной базой в Retail Rocket. + +## Поддержка региональности (склад/регион) + +Функционал региональности позволяет передавать информацию о товарах (например: цену и наличие), актуальную для конкретного склада/региона. Это позволяет везде, где используются данные товара, опираться на данные для конкретного склада или региона. + +Данные, которые могут быть переопределены для конкретного склада: + +* Цена; +* Старая цена; +* Признак наличия товара; +* Название товара; +* Описание товара; +* Ссылка на товар; +* Ссылка на изображение; +