API partenaire

Mise en cache des annonces

Les annonces obtenues à partir de points de terminaison de génération ne doivent pas être mises en cache à moins d'être absolument nécessaires, quel que soit leur type. Chaque fois qu'une page est chargée sur le site Web d'un détaillant, une nouvelle demande de génération d'annonces doit être envoyée à CitrusAd avec le contexte approprié pour générer un nouvel ensemble d'annonces.

Dans le cas où le détaillant ne peut prendre en charge cette fonction, CitrusAd propose une fonction de mise en cache grâce à laquelle un détaillant peut diffuser une annonce à plusieurs clients à plusieurs reprises.

🚧

Toute impression et tout clic répondant aux critères de validité de CitrusAd seront facturés en conséquence. Pour cette raison, CitrusAd conseille fortement de minimiser raisonnablement la période de mise en cache (à quelques minutes) afin de réduire le risque de dépenses excessives.

Exigences d'intégration

sessionId n'est plus requis dans la requête d'annonce car l'annonce peut être diffusée sur plusieurs sessions.

Tout détaillant souhaitant mettre en cache des annonces doit :

  • Définir un nouveau paramètre “cached”: true dans la requête d'annonce faite à CitrusAd, dans la section Options.
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "placement": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "options": {
                         "filterMode": "AndOr",
                         "cached": true
                             },
    "maxNumberOfAds": 3    
}
  • Pouvoir utiliser la méthode d'attribution sessionId lors du reporting des commandes.
  • Transmettre le sessionId encodé dans les rapports d'impressions et de clics.
  • Transmettre un horodatage des événements dans les rapports d'impressions et de clics. Le fuseau horaire entre les événements doit être identique, mais son choix est laissé à l'appréciation du détaillant. Format ISO-8601.
https://integration.<ENV>.citrusad.com/v1/resource/second-c/<AD_ID>?sessionId=<SESSION_ID>&event_ts=20220127152500

Une fois ceci en place, le traitement correspondant peut avoir lieu côté CitrusAd. Aucune configuration supplémentaire n'est requise par CitrusAd.

Fonctionnement de la mise en cache

Pour les annonces mises en cache, il existe une propriété configurable appelée « fenêtre ». Elle s'applique à tous les types d'annonces. De plus, la propriété « délai d'expiration » a déjà été transmise dans la réponse de CitrusAd
Nous utilisons ces propriétés pour déterminer la façon dont nous traitons les impressions et les clics. Dans certains cas, CitrusAd crée un nouvel adId et traite une impression/un clic en conséquence.
C'est ainsi que CitrusAd s'assure du bon fonctionnement de l'attribution sur plusieurs sessions client.

Scénario 1

Toute annonce portant le même sessionId dans la « fenêtre » sera traitée comme ayant le même adId.

2640

Scénario 2

Pour toute annonce avec différents sessionId, nous créerons un nouvel adId et le traiterons comme une nouvelle impression/un nouveau clic

2606

Scénario 3

Tout(e) impression/clic en dehors du délai d'expiration de l'annonce sera consigné(e) mais ne sera ni facturé(e) ni comptabilisé(e).

2612

Scénario 4

Si un clic se produit dans une fenêtre dans laquelle aucune impression n'est comptabilisée, CitrusAd en déduit qu'il s'agit d'un clic (comportement courant du système).

Ce phénomène peut être limité en augmentant la fenêtre et en réduisant le cache du détaillant.

2650

Chaque scénario peut se produire indépendamment en production si les annonces sont diffusées à plusieurs clients.

2670

🚧

Risque de dépenses excessives

Cette fonctionnalité permet à un détaillant de diffuser une annonce à plusieurs clients, plusieurs fois, sans avoir besoin d'en faire la demande à CitrusAd.

Cette fonctionnalité ne modifie en rien la façon dont les campagnes/portefeuilles sont modifiés. Plus la durée de mise en cache d'une annonce est longue, plus la probabilité de diffuser une annonce pour une campagne ou un portefeuille à court de fonds est élevée.

CitrusAd continuera à traiter et à facturer une impression/un clic pour une campagne/un portefeuille qui n'a plus de fonds disponibles au même tarif que lorsque le portefeuille avait des fonds.

Il existe trois manières de limiter les dépenses excessives pour ces scénarios.

  • Réduire la mise en cache au minimum de temps possible (préféré)
    Plus la durée de diffusion d'une annonce est longue, plus le risque de diffuser une annonce provenant d'une campagne/un portefeuille épuisé est grand.

  • CitrusAd réduit le « délai d'expiration » de toutes les annonces
    CitrusAd peut réduire le délai pendant lequel les annonces sont considérées comme « valides » après leur diffusion. Passé ce délai d'expiration, tou(te)s les impressions/clics sont invalidé(e)s.

  • CitrusAd élargit la « fenêtre » de toutes les annonces
    Une fenêtre plus large réduira le volume de nouvelles impressions/nouveaux clics. Cependant, cela réduit le nombre d'impressions/de clics comptabilisé(e)s