> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aftersell.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Пользовательская интеграция
> Вызывайте Strategies API напрямую для создания пользовательских решений на витрине — карусели на страницах товаров, кастомные апселлы в корзине и любые другие места, недоступные нативным поверхностям Aftersell.
## Обзор
Когда ни нативные поверхности Aftersell (post-purchase, оформление заказа, Upcart), ни готовая интеграция не подходят, вы можете самостоятельно вызывать Strategies API из вашей темы Shopify и отображать возвращенные товары так, как вам нужно.
Схема одинакова во всех случаях: сформируйте полезную нагрузку контекста в Liquid (чтобы атрибуты Shopify, такие как текущий товар, содержимое корзины и поля покупателя, заполнялись во время рендеринга), отправьте ее методом `POST` на `/api/public/strategy/evaluate` и отобразите ответ.
На этой странице рассмотрены две схемы реализации:
* **Контекст PDP** — добавьте секцию на страницы товаров, которая вызывает API с **просматриваемым в данный момент товаром** и отображает карусель возвращенных рекомендаций.
* **Контекст корзины** — отобразите блок апселла внутри кастомной корзины, который вызывает API со **всеми текущими позициями корзины** и отображает возвращенные товары.
Различие между ними — в форме **контекста товаров**: один товар на PDP, массив всех позиций в корзине.
***
## Что вам понадобится
1. **Ваш API-ключ Strategy.** В Aftersell перейдите в **Settings → Product Strategy** и в карточке **Security Token** скопируйте ваш токен (это и есть ваш API-ключ Strategy).
2. **Идентификатор Strategy.** Откройте нужную Strategy в редакторе Strategy Aftersell и скопируйте ее идентификатор.
3. **Доступ к коду темы.** Вы будете добавлять секцию Liquid (PDP) или блок (кастомная корзина) в вашу тему Shopify — Online Store → Themes → ... → Edit code.
Ваш API-ключ Strategy находится в клиентском коде темы, что делает его видимым для любого, кто просматривает исходный код страницы. Обращайтесь с ним как с публичными учетными данными витрины и обновите его в Aftersell в разделе **Settings → Product Strategy**, если он когда-либо окажется раскрыт нежелательным образом.
***
## Контекст PDP: сниппет секции
Эта схема добавляет секцию Shopify на страницу товара. При рендеринге страницы Liquid встраивает атрибуты текущего товара, корзины и покупателя в полезную нагрузку, затем JavaScript отправляет запрос в Strategies API и отображает возвращенные товары в карусели Splide.
### Установка
1. В админ-панели Shopify перейдите в **Online Store → Themes**, нажмите **...** на вашей теме и выберите **Edit code**.
2. В папке **Sections** создайте новый файл с именем `aftersell-upsell-carousel.liquid`.
3. Вставьте приведенный ниже сниппет в новый файл и замените `YOUR_STRATEGY_API_KEY` на API-ключ из Aftersell.
4. Сохраните.
5. Откройте шаблон товара (обычно `templates/product.json` или `sections/main-product.liquid`) и добавьте секцию **Aftersell Carousel** там, где должна появиться карусель. В редакторе темы вы также можете перетащить ее прямо на страницу товара.
6. В настройках секции вставьте ваш **идентификатор Strategy**.
### Что отправляет секция
Для каждого просмотра PDP полезная нагрузка включает:
* **products** — массив из одного элемента, содержащий просматриваемый в данный момент товар (productId, variantId, quantity, price, handle, title, vendor, productType, tags, collections, sellingPlan).
* **cart** — промежуточная сумма, количество товаров и количество позиций текущей корзины покупателя (опускается, если корзина пуста).
* **cartToken** — чтобы API мог связать это вычисление с той же сессией.
* **customer** — теги, страна, регион, локаль, количество заказов, общая сумма покупок и флаг согласия на маркетинг, но **только если покупатель авторизован**.
* **session** — код валюты из `shop.currency`.
Секция по умолчанию не отправляет UTM-параметры. Если вы хотите использовать таргетинг на основе UTM на PDP, зафиксируйте их на стороне клиента и добавьте в объект `session` перед вызовом fetch.
### Сниппет
```liquid theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
{% comment %}
Aftersell Carousel (Splide)
Type: Section — save to sections/aftersell-upsell-carousel.liquid
{% endcomment %}
{% if product %}
{{ section.settings.heading | default: 'You might also like' }}
Схема секции предоставляет четыре настройки, редактируемые продавцом: **Strategy ID**, **Heading**, **CTA Button Label** и **Max Products to Show**. Добавляйте или удаляйте настройки в блоке `{% schema %}`, чтобы предоставить редактору темы больше параметров.
CSS ограничен именами классов `.aftersell-*` и включает карусель на Splide с 4 карточками в ряд, которая переходит на 2 карточки при 768px и на 1 при 480px. Свободно редактируйте его под свою тему — ничего из этого не требуется для работы вызова API.
***
## Контекст корзины: блок апселла в кастомной корзине
Эта схема структурно совпадает со схемой для PDP, с одним ключевым отличием: **массив контекста товаров** формируется из позиций корзины, а не из просматриваемого в данный момент товара. Strategy тогда получает каждый товар, добавленный покупателем, и возвращает рекомендации на основе корзины в целом.
Реализация находится там же, где живет код вашей кастомной корзины, — в секции Liquid, отображающей cart drawer, в кастомном блоке headless-витрины или в шаблоне темы, таком как `cart.liquid`. Форма вызова API и обработка ответа идентичны примеру для PDP — отличается только массив `products`.
Структура выглядит так:
```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
var products = {{ cart.items | json }}.map(function(item) {
return {
productId: 'gid://shopify/Product/' + item.product_id,
variantId: 'gid://shopify/ProductVariant/' + item.variant_id,
quantity: item.quantity,
price: item.price / 100
// ...other fields as needed
};
});
```
Остальная часть полезной нагрузки (cart, customer, session, cartToken) и вызов `fetch` к `/api/public/strategy/evaluate` не отличаются от схемы для PDP выше — только массив `products` меняется с `[productContext]` на массив, полученный из корзины.
***
## Что происходит, когда Strategy возвращает результат
Форма ответа одинакова независимо от того, какой контекст вы отправили:
```json theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
{
"success": true,
"products": [ /* enriched recommended products */ ],
"evaluationId": "f3a1c2e0-...",
"resolution": { "strategyId": "...", "matchedRuleIds": [...], "fallbackUsed": false },
"meta": { "servedFromCache": false, "processingTimeMs": 12, "data": {} }
}
```
`evaluationId` — уникальный идентификатор этого вычисления. Если вы зафиксируете его и прикрепите к отображаемым товарам, вы сможете атрибутировать итоговый заказ к точной рекомендации, которая его породила, — см. [Атрибуцию](#attribution) ниже.
То, как вы отображаете массив `products`, полностью зависит от кода вашей темы. Приведенный выше сниппет для PDP отображает их как карусель карточек с выбором вариантов и кнопками добавления в корзину; кастомный блок корзины может отобразить их вертикальным списком внутри drawer.
Полную схему запроса и ответа см. в [справочнике Evaluate Strategy API](/ru/aftersell/strategies_api_reference_evaluate_strategy).
***
## Когда товар не возвращается
Если Strategy не вернула товары (`products: []`), обработка этого случая остается на усмотрение вашего кода. Приведенный выше сниппет для PDP полностью скрывает карусель. Кастомный блок корзины может вернуться к стандартному списку апселлов корзины или просто ничего не отображать.
Чтобы избежать пустого ответа, настройте **Catch all** в Strategy, чтобы всегда был резервный товар для возврата. О настройке Catch all см. страницу [Создание Strategies](/ru/aftersell/strategies_building_in_app).
***
## Советы по пользовательским интеграциям
* **Формируйте контекст в Liquid.** Liquid выполняется во время рендеринга и имеет доступ к полному графу объектов Shopify — товар, корзина, покупатель, магазин, запрос. Используйте его для заполнения полезной нагрузки на стороне сервера вместо клиентских вызовов.
* **Не публикуйте API-ключ в открытых репозиториях.** Он окажется в коде вашей темы, который доставляется в браузер, — это нормально. Но не вставляйте эту же тему в публичный репозиторий и не делитесь сборкой с посторонними.
* **Используйте Catch all.** Витрина выглядит сломанной, когда слот исчезает. Catch all с небольшим набором безопасных значений по умолчанию сохраняет согласованность интерфейса.
* **Кешируйте там, где это уместно.** Strategies API выполняет легкое кеширование на стороне сервера (`meta.servedFromCache`), но для страниц товаров с высоким трафиком имеет смысл также применять debounce или мемоизацию вызовов на клиенте (например, не вызывать API повторно, когда один и тот же товар отображается дважды за сессию).
***
## Атрибуция
Когда покупатель нажимает кнопку добавления в корзину в сниппете, вызов `/cart/add.js` прикрепляет **свойства позиции (line item properties)** к товару в корзине:
```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
properties: {
"_source": "Aftersell",
"_attribution": "CTA"
}
```
Эти свойства сопровождают позицию вплоть до заказа Shopify, где они появляются в записи позиции. Вы можете использовать их дальше по цепочке для атрибуции выручки, фильтрации заказов или передачи в аналитические инструменты, которые читают свойства позиций.
Ключи и значения — это соглашения, а не требования: вызов API работает одинаково независимо от того, что вы здесь укажете. Изменяйте их под собственную модель атрибуции. Например:
```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
properties: {
"_source": "PDP Carousel",
"_strategy_id": "{{ section.settings.strategy_id }}",
"_campaign": "summer-2026"
}
```
Ключи свойств, начинающиеся с подчеркивания (`_`), скрыты из интерфейса корзины и оформления заказа, но все равно прикрепляются к заказу. Используйте префикс с подчеркиванием для метаданных атрибуции, которые вы не хотите показывать покупателям.
Применяйте ту же схему в реализации с контекстом корзины — любой вызов добавления в корзину из кастомного блока апселла может передавать любые нужные вам свойства.
### Атрибуция к конкретному вычислению
Чтобы связать заказ с **конкретным вычислением**, которое порекомендовало товар, — а не просто с фактом «пришло из Strategy», — зафиксируйте `evaluationId` из ответа и прикрепите его к позиции в свойстве `__as_offer_id`. AfterSell читает этот ключ, поэтому заказы, помеченные им, атрибутируются к конкретному вычислению в отчетности.
В обработчике `evaluate()` сохраните идентификатор из ответа:
```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
.then(function(data) {
if (!data || !data.success || !data.products || !data.products.length) {
clearSkeletons(); return;
}
evaluationId = data.evaluationId; // declare `var evaluationId;` alongside your other state
renderCards(data.products.slice(0, MAX_PRODUCTS));
})
```
Затем включите его в свойства добавления в корзину:
```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
properties: Object.assign(
{ "_source": "Aftersell", "_attribution": "CTA" },
evaluationId ? { "__as_offer_id": evaluationId } : {}
)
```
Сохраняйте двойное подчеркивание в `__as_offer_id` — это ключ, который ищет AfterSell, а префикс с подчеркиванием скрывает его от покупателей. Если `evaluationId` отсутствует (например, товары не были возвращены), пропустите это свойство, а не отправляйте пустое значение.
