API partenaire

Catalogue et produits

Pour intégrer CitrusAd, vous aurez besoin d'au moins un catalogue de produits.

Qu'est-ce qu'un catalogue ?

Un catalogue est un groupe de produits accompagnés de leurs attributs, le plus souvent utilisé pour regrouper tous les produits du site d'un intégrateur sous un seul catalogue.

Les annonceurs sélectionnent les catalogues lors du processus de création des campagnes, afin que celles-ci ne diffusent que les produits du catalogue sélectionné. Tous les produits sont généralement regroupés dans un seul catalogue pour chaque intégrateur, ce qui simplifie la sélection pour les annonceurs.

Il est possible de créer plusieurs catalogues afin de segmenter la disponibilité des produits entre différents détaillants ou pays à des fins de ciblage de campagne.

📘

Si vous souhaitez créer plusieurs catalogues, contactez votre responsable de compte technique pour connaître les options recommandées, car il existe peut-être des méthodes de ciblage plus adaptées.

🚧

Si vous effectuez une intégration dans un espace de noms de réseau, vous devez créer un seul catalogue.

Que sont les produits ?

Les produits sont des GTIN individuels sur le site d'un intégrateur. Les produits sont synchronisés avec CitrusAd avec des valeurs et attributs d'identification individuels. Chaque produit doit représenter un GTIN/SKU dans votre catalogue de produits actuel.

Les produits sont sélectionnés par les annonceurs lors de la création de la campagne. Seuls les produits associés aux catalogues sélectionnés par l'annonceur s'affichent. Chaque produit doit représenter un GTIN unique. Les variantes d'un même produit doivent être répertoriées comme des produits distincts, par exemple : les variantes de 200 ml, 600 ml et 2 l de la même boisson doivent être considérées comme trois produits différents dans CitrusAd, en accord avec les bonnes pratiques existantes en matière d'intégration.

Filtres de produits : explication

Les filtres de produits sont principalement utilisés pour la génération d'annonces en plus de contenir des propriétés telles que imageUrl et name. Lorsque vous effectuez des requêtes d'annonces auprès de CitrusAd, du contexte contenant des informations pertinentes sur la page est envoyé afin de garantir que des publicités pertinentes sont diffusées sur chacune d'entre elles.

La structure des filtres dépend de l'intégrateur, mais il convient de noter que ces filtres de produits seront envoyés dans votre contexte de génération d'annonces. Les filtres de produits doivent correspondre exactement à ce qui est demandé dans la génération d'annonces.

Voici un exemple de contexte contenant des productFilters  :

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
}

Ce contexte renverra uniquement des annonces pour les produits contenant tous les filtres dans le tableau correspondant.

📘

Si vous souhaitez utiliser les enchères minimales de catégories, assurez-vous que vos catégories sont conviviales et faciles à comprendre pour les annonceurs qui créent des campagnes. Par exemple, category:Keyboards est plus facile à comprendre que category:12.

Fournir des images et des noms de produits

CitrusAd a besoin d'informations sur les images et les noms de produits pour les rendre consultables lors de la création de campagnes dans le portail CitrusAd. Ces valeurs peuvent être envoyées à CitrusAd dans des balises formatées comme dans l'exemple suivant :

POST $BASE_URL/v1/catalog-products?teamId=<YOUR_TEAM_ID> HTTP/1.1 
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "catalogProducts": [
        {
            "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
            "gtin": "23556578965543",
            "inventory": 50,
            "price": "19.99",
            "tags": [
                 ""imageurl:https://your.image.host.com/image.jpg","name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
            ],
            "filters": [
                 "category:Health&Beauty","category:Grocery","Brand:Covergirl","Special_Flag:0"
            ]
        }
    ]
}

Elles sont visibles dans différentes zones du portail CitrusAd, y compris lors de la sélection des produits, comme dans l'exemple ci-dessous :

1581

Image de référence