API partenaire

Requêtes de pages de marque

Point de terminaison de la page de marque

La plateforme de pages de marque utilise des URL et des chemins d'accès autonomes vers les points de terminaison de la génération d'annonces. Votre responsable de compte technique vous fournira votre URL de base pour les environnements de sandbox et de production.

Authorization

L'autorisation pour l'outil de pages de marque est l'authentification du porteur. Votre responsable de compte technique pourra vous fournir votre porteur de jeton d'authentification pour les environnements de sandbox et de production.

Vous devrez envoyer le jeton dans les en-têtes sous la forme header 'Authorization: Bearer ${apiKey}

Requête

Pour demander une page de marque, vous devez envoyer une demande GET au point de terminaison brand-pagede CitrusAd avec l'URL que vous demandez pour

curl --location --request GET '${URL}/api/v1/brand-page:static?url=${url}&retailer=${retailer}' \
--header 'Authorization: Bearer ${apiKey}

🚧

Assainissement des paramètres de requête des URL

Lorsque vous demandez des annonces, vous devez supprimer tous les paramètres de requête relatifs à votre site des paramètres envoyés à CitrusAd.

Au sein de la plateforme CitrusAd, nous utilisons cette URL pour récupérer l'URL exacte de la page demandée. Nous allons faire correspondre https\:www.retailer.com/brand/lollipops-brand, mais pas si des paramètres de requête supplémentaires sont spécifiés.

Réponse

En fonction de la configuration de votre page de marque, les réponses du segment varient en raison des deux segments intégrés et du modèle de la page de marque.

Si vous souhaitez passer en revue les fonctionnalités de personnalisation, consultez la page Structure de haut niveau.

Composants de réponse

Conteneur

Le conteneur contient les informations relatives à l'ensemble des réponses de la page de marque. Il contient également un tableau de données d'objets dans lequel sont conservées les réponses des segments.

{
  "id": "string",
  "brandPageId": "string",
  "brandPageTemplateId": "string",
  "data": [
  ]
}

L'AD_ID data tableau sera alimenté par des segments, en fonction de la configuration de la page de marque ; le format des segments est détaillé ci-dessous.

Segments

En raison des possibilités de personnalisation du produit des pages de marque, la réponse exacte que vous recevrez dépendra de votre configuration. Chaque segment possédera un id et un name, en plus des propriétés spécifiques au segment.

Segments de bannière

À l'intérieur du data tableau, chaque segment est un objet, comme ci-dessous :

📘

Les attributs spécifiques à la bannière x dans la réponse ne sont donnés qu'à titre d'exemple. Les valeurs de la réponse sont configurées par modèle et peuvent être personnalisées, par exemple backgroundImage, brandLogo, ou selon vos besoins.

 {
        "id": "26f6117c-147b-4447-86aa-992e9ddb0daa",
        "name": "primary-content",
    	  "headingText": "Banner For MasterFoods Beef Stroganoff with Shop Now button",
    	  "bannerText": "<strong>The Perfect Mid-Week Dinner</strong>",
    	  "bannerTextColour": "#fff",
   		  "heroImage": "https://storage.googleapis.com/assets-images/coke/2853856c8644",
  	    "heroImageAltText": "<i>Picture of the Dolmio Pasta Sauce</i>",
	      "secondaryHeroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8m435c34r",
	      "secondaryHeroImageAltText": "Milo Logo",
	      "secondaryHeroMode": "landscape",
	      "backgroundColour": "895b5b",
	      "backgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
	      "backgroundImagePosition": "FILL",
  	    "secondaryBackgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada"
}

Pour plus d'informations sur les possibilités offertes par les segments de bannière, reportez-vous à la rubrique Structure de haut niveau.

Segments de contenu

À l'intérieur du data tableau, chaque segment est un objet, comme ci-dessous :

📘

heroText,heroTextColouret heroSubText sont des exemples pour notre détaillant type. Chaque champ peut être nommé selon le type de champ approprié, par exemple paragraphText.

 {
        "id": "26f6117c-147b-4447-86aa-992e9ddb0daa",
        "name": "primary-content",
        "heroText": "<i>What a way to start your week</i>",
        "heroTextColour": "#000000",
        "heroSubText": "<i>What a way to start your week</i>",
}

Pour plus d'informations sur les possibilités offertes par les segments de contenu, reportez-vous à la rubrique Structure de haut niveau.

Segments de produits

À l'intérieur du data tableau, chaque segment est un objet, comme ci-dessous :

📘

Ce format de réponse est fixe et ne peut être personnalisé

 {
      "id":  "988dc393-a37a-421c-9b08-25f0f9e575f8",
      "name": "my-products",
      "productSelection": [
        {
          "catalogId": "1b5a2521-9e79-4b95-99b0-4deffc586d81",
          "position": 3,
          "productCode": "f069585b-a364-4795-9eb3-6a978c513ba4",
          "sellerId": "123"
        },
        {
          "catalogId": "1b5a2521-9e79-4b95-99b0-4deffc586d81",
          "position": 2,
          "productCode": "f069585b-a364-4795-9eb3-6a978c513ba4",
          "sellerId": "123"
        },
        {
          "catalogId": "1b5a2521-9e79-4b95-99b0-4deffc586d81",
          "position": 1,
          "productCode": "f069585b-a364-4795-9eb3-6a978c513ba4",
          "sellerId": "123"
        }
      ]
    }

📘

Informations sur le produit

À l'instar de l'intégration standard des annonces de produits, CitrusAd ne propose pas d'attributs de produits tels que le nom, le prix et l'image. Ces informations devront être extraites d'un serveur interne d'informations sur les produits (ou d'un serveur similaire) sur l'infrastructure du détaillant.

Bien qu'il s'agisse d'un effort d'intégration supplémentaire, cela garantit qu'il n'y a pas de dépendance vis-à-vis de Citrus lors de la mise à jour et de la modification des informations tarifaires, ainsi que de tout graphique automatisé du type « offre spéciale », « 20 % de réduction », ou tout autre contenu similaire dépendant de CitrusAd.

Pour plus d'informations sur les possibilités offertes par les segments de produits, reportez-vous à la rubrique Structure de haut niveau.

Interprétation de la réponse

Dans la réponse, chaque segment possède un id et un name. Ceux-ci seront propres à un segment au sein d'un modèle. Vous pouvez les utiliser pour identifier différents types de composants, comme le type de bannière ou le type de contenu, et les aligner à l'endroit où vous les injectez.

Exemple de réponse

Voici un exemple de réponse à une page de marque pour un modèle avec une bannière, un contenu et un segment de produit.

📘

CUSTOM_ID_N est un exemple d'identifiant défini par le détaillant, comme paragraphText.

Réponse

{
  "id": "string",
  "brandPageId": "string",
  "brandPageTemplateId": "string",
  "data": [
    {
      "id":  "string",
      "name": "string",
      "CUSTOM_ID_1": "string",
      "CUSTOM_ID_2": "string",
      "CUSTOM_ID_3": "string"
    },
    {
      "id":  "string",
      "name": "string",
      "productSelection": [
        {
          "catalogId": "string",
          "position": integer,
          "productCode": "string",
          "sellerId": "string"
        },
        {
          "catalogId": "string",
          "position": integer,
          "productCode": "string",
          "sellerId": "string"
        },
        {
          "catalogId": "string",
          "position": integer,
          "productCode": "string",
          "sellerId": "string"
        }
      ]
    },
    {
      "id":  "string",
      "name": "string",
      "CUSTOM_TEXT_FIELD_ID_1": "VALUE",
      "CUSTOM_COLOUR_FIELD_ID_1": "VALUE",
      "CUSTOM_TEXT_FIELD_ID_2": "VALUE",
    }
  ]
}

Vous souhaitez voir d'autres modèles et exemples ? Voir Exemples de modèles de page de marque.