Personnalisation des mises en page

Audience

Cette surface API est destinée aux partenaires d'intégration construisant sur le réseau Rokt. Les partenaires e-commerce de Rokt construisant leur propre intégration directe devraient se référer au Guide d'intégration du SDK Rokt Ecommerce.

Cette recette couvre le cycle complet de personnalisation de mise en page sur un marchand déjà intégré : thématiser une mise en page, basculer la page vers l'autre type de mise en page, thématiser la nouvelle mise en page, et revenir en arrière. Deux endpoints réalisent le travail (le PATCH de mise en page et le PUT de changement de page), et la réponse d'enregistrement vous donne les identifiants nécessaires pour les deux. Pour le modèle sous-jacent (surfaces, types de mise en page, tokens de thème), voir Pages et mises en page.

remarque

L'endpoint de modification de mise en page est la seule surface PATCH dans l'API de partenariat : il accepte des mises à jour sparse. Envoyez uniquement les clés de thème que vous souhaitez modifier ; tout le reste est préservé. C'est l'opposé des sémantiques SET sur les endpoints de contrôles.

1
Capture layout_id and page_id from registration
Chaque entrée pages[] sur la réponse d'enregistrement (ou ajout de pages) contient les deux identifiants utilisés dans cette recette : layout_id pour les modifications de thème et page_id pour les changements de type de mise en page. Stockez les deux par marchand et par surface.
{ "account_id": "<your-account-id>", "pages": [ { "surface": "confirmation", "page_id": "bfb5b9be-1234-4abc-9def-aaaabbbbcccc", "layout_id": "9d11d8aa-5678-4def-9abc-bbbbccccdddd", "page_identifier": "confirmation_page" } ] }

Apply theme edits

Envoyez un PATCH sparse à la mise en page. Cinq tokens de thème sont exposés (primaryColor, backgroundColor, textColor, borderRadius, closeButtonColor), et tous les cinq sont optionnels.

curl -X PATCH https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/layouts/9d11d8aa-5678-4def-9abc-bbbbccccdddd \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Platform-Parent-Account-Id: $PARENT" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "primaryColor": "#FF6B35",
    "backgroundColor": "#FFFFFF",
    "borderRadius": 8
  }'

{
  "status": "ok",
  "layout_id": "9d11d8aa-5678-4def-9abc-bbbbccccdddd",
  "layout_template_version": "3.0.7"
}

layout_template_version est la version du modèle sur laquelle la mise en page a été enregistrée. Rokt passe automatiquement à la dernière version publiée à chaque enregistrement, elle peut donc être plus récente que celle enregistrée avant votre modification.

3
Switch the page's layout type
Déplacez la page vers l'autre type de mise en page (ici Overlay → Embedded) avec le PUT de changement de page. Le page_id est celui capturé à l'étape 1.
curl -X PUT https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/pages/bfb5b9be-1234-4abc-9def-aaaabbbbcccc \ -H "Authorization: Bearer $TOKEN" \ -H "X-Platform-Parent-Account-Id: $PARENT" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "platform_integration": "<your-preset-key>", "layout_type": "Embedded" }'
{ "status": 200, "error": null, "message": "ok", "request_id": "0e3a1b9c-1234-4abc-9def-aaaabbbbcccc", "data": { "status": "ok", "page": { "surface": "confirmation", "page_id": "bfb5b9be-1234-4abc-9def-aaaabbbbcccc", "layout_id": "f8700369-5678-4def-9abc-bbbbccccdddd", "page_identifier": "confirmation_page" } } }
Le data.page.layout_id de la réponse est la mise en page maintenant active sur la page. Capturez-le, car les modifications de thème ultérieures doivent cibler cet ID. Le layout_id de l'étape 1 se réfère maintenant à la mise en page inactive. page_id et page_identifier restent inchangés : votre code SDK continue de passer le même identifiant dans selectPlacements, bien qu'une mise en page Embedded nécessite <div id="rokt-container"></div> sur la page du marchand.
remarque
Demander le layout_type que la page utilise déjà recevra une réponse 200, et aucun changement ne sera effectué. Cela peut être appelé en toute sécurité dans le cadre d'une boucle de réconciliation.

Theme the new layout (optional)

La nouvelle mise en page démarre à partir du modèle canonique Rokt pour son type ; les modifications de thème de l'étape 2 appartiennent à l'ancienne mise en page, pas à celle-ci. PATCH le layout_id capturé de la réponse de changement si le marchand souhaite également thématiser la nouvelle mise en page.

curl -X PATCH https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/layouts/f8700369-5678-4def-9abc-bbbbccccdddd \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Platform-Parent-Account-Id: $PARENT" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "primaryColor": "#FF6B35",
    "borderRadius": 8
  }'

Switch back: theme edits are preserved

Revenir à un type de mise en page utilisé précédemment par la page restaure la mise en page précédente, y compris ses modifications de thème. La réponse renvoie le layout_id original de l'étape 1 ; le primaryColor, backgroundColor, et borderRadius que vous avez définis à l'étape 2 sont toujours appliqués.

curl -X PUT https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/pages/bfb5b9be-1234-4abc-9def-aaaabbbbcccc \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Platform-Parent-Account-Id: $PARENT" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "platform_integration": "<your-preset-key>",
    "layout_type": "Overlay"
  }'

{
  "status": 200,
  "error": null,
  "message": "ok",
  "request_id": "0e3a1b9c-1234-4abc-9def-aaaabbbbcccc",
  "data": {
    "status": "ok",
    "page": {
      "surface": "confirmation",
      "page_id": "bfb5b9be-1234-4abc-9def-aaaabbbbcccc",
      "layout_id": "9d11d8aa-5678-4def-9abc-bbbbccccdddd",
      "page_identifier": "confirmation_page"
    }
  }
}

Erreurs courantesLien direct vers Erreurs courantes

422 : valeur de layout_type non reconnue

Renvoyé lorsque layout_type n'est pas une valeur d'énumération reconnue (par exemple, une faute de frappe ou une chaîne inconnue). La validation des entrées de l'API intercepte cela avant que la requête n'atteigne la couche de transactions. Vérifiez la valeur que vous avez passée par rapport à l'énumération documentée : Overlay et Embedded.

400 : layout_type valide mais non pris en charge pour cette surface

Renvoyé lorsque layout_type est une valeur d'énumération valide mais non prise en charge pour la surface de cette page dans votre intégration. Le message d'erreur indique les valeurs acceptées par votre préréglage. Contactez votre interlocuteur Rokt si vous n'êtes pas sûr de ce que votre intégration accepte.

404 : page ou mise en page inconnue

Le page_id (sur le PUT de changement) ou layout_id (sur le PATCH de thème) n'existe pas sur le compte, a été archivé, ou le account_id n'est pas accessible à votre compte gestionnaire. Revérifiez les identifiants par rapport à l'enregistrement ou à la réponse d'ajout de pages, et souvenez-vous qu'après un changement, le PATCH de thème doit cibler le layout_id de la réponse de changement, pas celui que vous avez capturé avant. Voir Erreurs pour la forme de l'enveloppe.

422 : page ou mise en page non dans un état éditable/modifiable

La page n'a pas été créée via le flux de partenariat (PUT de changement), ou la mise en page n'a pas été créée via l'intégration de partenariat (PATCH de thème). Chaque page_id et layout_id retourné par l'enregistrement ou l'ajout de pages est modifiable et éditable, donc les partenaires utilisant le flux standard ne devraient pas voir cela. Un 422 avec error: "ValidationFailed" signifie plutôt qu'un en-tête requis est manquant ; vérifiez X-Platform-Parent-Account-Id.

Les deux points de terminaison partagent les limites de taux (rate limits) d'écriture standard rate limits. Sur un 429, respectez Retry-After et réessayez avec la même Idempotency-Key.