本ドキュメントでは、検索プレースメント、カテゴリプレースメント、ワイドディスプレイ（ホーム、精算、特別アイテムなど）で商品広告を生成するためのベストプラクティスを概説しています。これらの戦略を実施することで、広告の関連性とターゲットを絞ることができ、ユーザーのエンゲージメントと満足度が向上します。強化された機能には、パーソナライズされた広告アプローチのためのページネーション、フィルター検索、位置情報ベースのフィルタリングなどがあります。

検索プレースメントとカテゴリプレースメントを使用して商品広告を生成するには、次のトピックを参照してください。

リクエストのページネーション

ページネーションは、大量のデータを個別のページまたはセグメントに分割して管理するために使用される手法です。商品広告の生成では、ページを分割することによって、ユーザーが一度に多くの広告に圧倒されたり、以前に閲覧した広告が重複して配信されることがなくなります。

商品広告を生成すると、レスポンスにはmemoryTokenが含まれます。このトークンは、どの広告がすでに配信されたかを追跡するのに役立ちます。後続の広告リクエストにこのmemoryTokenを含めることで、以前に配信された広告が新しい広告レスポンスから除外され、全く新しくそして関連性の高い広告が表示されるため、ユーザー体験が向上します。

最初のリクエスト：商品広告を生成し、レスポンスでmemoryTokenを受け取ります。
後続のリクエスト：以前に配信された広告をレスポンスから除外するために、後続の広告リクエストにmemoryTokenを含めます。

詳細については、ページネーションを参照してください。

リクエスト指標

リクエスト本体は、次のフィールドを含むJSONオブジェクトである必要があります。

対象	type	説明
customerId	文字列、必須	顧客用の一意の識別子。これは小売業者から提供されます。
sessionId	文字列、必須	セッション用の一意の識別子。これは帰属表示に必要であり、小売業者によって提供されます。
placement	文字列、必須	広告が表示されるコンテキスト（例：「検索」）。
catalogId	文字列、必須	商品のフィルタリング元となる商品カタログ用の一意の識別子。catalogIDは、EpsilonのRetail Media UIまたは小売業者から取得できます。
maxNumberOfAds	整数、必須	表示する広告の最大数。
searchTerm	文字列、検索プレースメントに必須	カタログ内で検索する用語。
memoryToken	文字列、必須	以前に配信された広告を除外するトークン。
options	オブジェクト、オプション	Additional options such as filtering modes `AndOr`. If specified, the system will use both "AND" and "OR" conditions to narrow down the search results.

リクエスト例

次の例では、最初の広告リクエストは「chocolate」という用語を含む検索プレースメント用です。memoryTokenは、同じ検索用語とコンテキストに対して以前に配信された広告がレスポンスから除外されるようにするために含まれています。optionsのオブジェクトはフィルタリングモードを指定し、maxNumberOfAdsはレスポンスで生成される広告数の上限を設定します。

ページネーションとメモリのトークンを活用することで、冗長性を回避して関連性を高めて、よりダイナミックで魅力的な広告体験をユーザーに提供できます。

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9", 
    "placement": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0=",
    "options": {
                         "filterMode": "AndOr"
                             },
    "maxNumberOfAds": 3    
}

レスポンス例

すべての商品広告レスポンスは標準のJSON形式に従っています。商品広告は広告配列で返されます。

id：インプレッションとクリックのレポートで使用される広告ID。
gtin：商品のGlobal Trade Item番号。
discount：広告に適用される割引に関する詳細。
- amount：割引額
- minPrice：割引の最低価格。
- maxPerCustomer：顧客が割引で購入できる商品の最大数。
expiry：広告の有効期限の日時。
position：レスポンスペイロード内の広告の位置。固定テナントプレースメントが正しく表示されるよう、常に位置フィールドを読み、それを守る必要があります。

{
    "ads": [
        {
            "id": "display_QqHaKRrKlFm1Wxr9c_DXJN4HSE3NzMzNjM2",
            "gtin": "7733636",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400902957Z",
            "position": 1
        },
        {
            "id": "display_NzsHqP0_iQedlo9VnrO2vqkwi_k3NzMzNjI4",
            "gtin": "7733628",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400908257Z",
            "position": 2
        },
        {
            "id": "display_xNeShqidaMuEqiJ0zNdt-Gzygjs3NzE0MTA3",
            "gtin": "7714107",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400912929Z",
            "position": 3
        },
        {
            "id": "display_3rGiryPskhQusmsf43nghbQwnqo3NzMzNjU3",
            "gtin": "7733657",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400917769Z",
            "position": 4
        }
    ],
    "banners": [],
    "products": [],
    "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0="
}

マーケットプレイスの出品者登録を行うと、広告レスポンスに追加のsellerIdフィールドが表示される場合があります。このフィールドは、キャンペーンの所有チームがEpsilon Retail Media UIで出品者IDを設定した場合にのみ含まれます。

出品者IDを使用した例

{
    "ads": [
        {
            "id": "display_QqHaKRrKlFm1Wxr9c_DXJN4HSE3NzMzNjM2",
            "gtin": "7733636",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400902957Z",
            "position": 1
        },
        {
            "id": "display_NzsHqP0_iQedlo9VnrO2vqkwi_k3NzMzNjI4",
            "gtin": "7733628",
            "sellerId": "2834-ascre-2wcr4",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400908257Z",
            "position": 2
        }
    ],
    "banners": [],
    "products": [],
    "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0="
}

検索のフィルタリング

顧客が検索にフィルターを適用すると、productFiltersを使用してクエリのコンテキストを強化できます。これにより、特定のカテゴリや属性に基づいて、より正確に広告を絞り込むようにできます。以下の例では、カテゴリの「Cupboard」と食事制限の「Gluten-free」でフィルタリングする方法を示します。この方法は、どのようなカテゴリでも、または大まかな一致でのプレースメントでも適応できます。

リクエスト指標

リクエスト本体は、次のフィールドを含むJSONオブジェクトである必要があります。

対象	type	説明
customerId	文字列、必須	顧客用の一意の識別子。これは小売業者から提供されます。
sessionId	文字列、必須	セッション用の一意の識別子。これは帰属表示に必要であり、小売業者によって提供されます。
placement	文字列、必須	広告が表示されるコンテキスト（例：「検索」）。
catalogId	文字列、必須	商品のフィルタリング元となる商品カタログ用の一意の識別子。catalogIDは、EpsilonのRetail Media UIまたは小売業者から取得できます。
maxNumberOfAds	整数、必須	表示する広告の最大数。
searchTerm	文字列、検索プレースメントに必須	カタログ内で検索する用語。
productFilters	配列、必須	カテゴリフィルターを含む配列。
options	オブジェクト、オプション	Additional options such as filtering modes `AndOr`. If specified, the system will use both "AND" and "OR" conditions to narrow down the search results.

リクエスト例

このサンプルリクエストでは、HTTP POSTメソッドを使用して、指定されたエンドポイントにJSONオブジェクトを送信します。productFilters配列は、検索をカテゴリ「Cupboard」と食事制限「Gluten-free」でフィルタリングすることを指定します。オプションオブジェクトはfilterModeをAndOrに設定し、フィルタリングで柔軟な組み合わせを実行できるようにします。maxNumberOfAdsフィールドは、表示される広告の数を3つに制限します。

この構造に従うことで、顧客の検索条件に関連性の高いターゲット広告キャンペーンを作成し、全体的なユーザー体験を向上させることができます。

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9", 
    "placement": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "productFilters": [
     	 ["category:Cupboard"],["dietary:Gluten-free"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

位置情報で絞り込む

カタログで位置情報フィルタを同期している場合、コンテキストを拡張してproductFiltersで顧客のストアの位置情報を提供できます。この機能を使用すると、特定の店舗の位置情報に基づいて広告を絞り込むことができ、顧客にもっと関連性の高い広告を表示できます。

リクエスト指標

リクエスト本体は、次のフィールドを含むJSONオブジェクトである必要があります。

対象	type	説明
customerId	文字列、必須	顧客用の一意の識別子。これは小売業者から提供されます。
sessionId	文字列、必須	セッション用の一意の識別子。これは帰属表示に必要であり、小売業者によって提供されます。
placement	文字列、必須	広告が表示されるコンテキスト（例：「検索」）。
catalogId	文字列、必須	商品のフィルタリング元となる商品カタログ用の一意の識別子。catalogIDは、EpsilonのRetail Media UIまたは小売業者から取得できます。
maxNumberOfAds	整数、必須	表示する広告の最大数。
searchTerm	文字列、検索プレースメントに必須	カタログ内で検索する用語。
productFilters	配列、必須	カテゴリフィルターを含む配列。
options	オブジェクト、オプション	Additional options such as filtering modes `AndOr`. If specified, the system will use both "AND" and "OR" conditions to narrow down the search results.

リクエスト例

このサンプルリクエストでは、HTTP POSTメソッドを使用して、指定されたエンドポイントにJSONオブジェクトを送信します。

productFilters配列は、検索を次の基準でフィルタリングすることを指定します。
- カテゴリー："Cupboard"
- 食事制限："Gluten-free"
- 位置情報："Westenbury"
オプションオブジェクトはfilterModeをAndOrに設定し、フィルタリングで柔軟な組み合わせを実行できるようにします。
maxNumberOfAdsフィールドは、表示される広告の数を3つに制限します。

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9", 
    "placement": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "productFilters": [
     	 ["category:Cupboard"],["dietary:Gluten-free"],["location:Westenbury"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}