Pages et Dispositions

Audience

Cette surface API est destinée aux partenaires d'intégration construisant sur le réseau Rokt. Les partenaires e-commerce de Rokt intégrant des placements sur leur propre page de paiement devraient utiliser les documents développeur Rokt Ecommerce à la place.

La plupart des intégrations partenaires permettent à chaque marchand d'afficher des placements Rokt sur plus d'une surface. Le tableau optionnel pages sur POST /v1/accounts/register/partnership déclare quelles surfaces un marchand utilise et quel style de disposition chaque surface obtient. Rokt crée une page et une disposition par entrée et retourne les identifiants dont votre code SDK a besoin pour les afficher.

Les trois surfacesLien direct vers Les trois surfaces

Chaque entrée dans pages choisit l'une des trois surfaces. Chacune correspond à un contexte de page distinct avec des règles côté Rokt ajustées pour cette intention.

`surface`	Quand l'utiliser	Compte comme une transaction ?
`confirmation`	La page de confirmation de commande affichée immédiatement après la finalisation de l'achat.	Oui
`tracking`	La page de suivi d'expédition ou de commande que le client visite après l'achat.	Non
`returns`	Le portail de retours où le client initie ou consulte un retour.	Non

confirmation est une surface transactionnelle. tracking et returns sont des surfaces d'engagement post-achat ; elles ne consignent pas délibérément les transactions même si elles apparaissent après l'achat. Utilisez la surface qui correspond à l'intention du client sur cette page, pas celle qui est la plus proche de votre nom de page interne.

remarque

La surface payment (la page affichée pendant le paiement, avant la finalisation de la commande) est intentionnellement différée à une version ultérieure ; les pages de paiement nécessitent leurs propres contrôles et un traitement de qualité réservée qui est encore en cours de définition. Contactez votre interlocuteur Rokt si vous avez un cas d'utilisation pour une surface de paiement.

Les deux types de dispositionLien direct vers Les deux types de disposition

Chaque entrée pages associe la surface à un style de disposition.

Overlay

Un modal qui apparaît sur la page du marchand lorsque le placement est déclenché. Idéal pour les surfaces où vous souhaitez l'attention complète du client.

Embedded

S'affiche en ligne dans un élément ancre sur la page du marchand. Le sélecteur d'ancre par défaut est #rokt-container; la page du marchand doit inclure <div id="rokt-container"></div> où le placement doit s'afficher.

Vous pouvez mélanger et assortir Overlay et Embedded (par exemple, Overlay sur confirmation et Embedded sur tracking) en listant chaque surface séparément dans le tableau pages avec son propre layout_type.

remarque

Certaines intégrations ne prennent en charge qu'un sous-ensemble de types de disposition. Si vous passez un layout_type qui n'est pas une valeur enum reconnue (par exemple, une faute de frappe ou une chaîne inconnue), vous recevrez un 422 de la couche de validation d'entrée. Si layout_type est une valeur enum valide mais non prise en charge pour la surface de cette page sur votre intégration, vous recevrez un 400 du serveur nommant les valeurs autorisées. Contactez votre interlocuteur Rokt si vous n'êtes pas sûr de ce que votre intégration accepte.

Chaque intégration a un défautLien direct vers Chaque intégration a un défaut

Votre intégration est livrée avec un défaut pages adapté à ses surfaces et types de disposition attendus. Omettez le champ lors de l'enregistrement pour l'utiliser. Passez pages pour remplacer. Cela est utile lorsque vous souhaitez un type de disposition différent par surface, ou seulement un sous-ensemble de l'ensemble par défaut. Si vous passez une combinaison (surface, layout_type) que votre intégration ne prend pas en charge, vous recevrez un 400 nommant les valeurs prises en charge. Envoyer pages: [] est traité de la même manière que l'omission du champ.

Demande et réponseLien direct vers Demande et réponse

Passez le tableau sur POST /v1/accounts/register/partnership:

{
  "brand": "Acme Apparel",
  "vertical_id": 1500,
  "sub_vertical_id": 1610,
  "country_code": "US",
  "platform_parent_account_id": "<your-platform-parent-account-id>",
  "store_identifier": "https://acme-apparel.example.com",
  "external_account_id": "partner-merchant-abc123",
  "pages": [
    { "surface": "confirmation", "layout_type": "Overlay"  },
    { "surface": "tracking",     "layout_type": "Embedded" },
    { "surface": "returns",      "layout_type": "Embedded" }
  ]
}

La réponse contient un tableau pages correspondant avec une entrée par surface. Chaque entrée indique à votre code SDK quelle chaîne page_identifier passer dans selectPlacements:

{
  "account_id": "<your-account-id>",
  "pages": [
    { "surface": "confirmation", "page_id": "bfb5b9be-...", "layout_id": "9d11d8aa-...", "page_identifier": "confirmation_page" },
    { "surface": "tracking",     "page_id": "2b9d8a5e-...", "layout_id": "f8700369-...", "page_identifier": "tracking_page" },
    { "surface": "returns",      "page_id": "7a31963a-...", "layout_id": "4865f1ab-...", "page_identifier": "returns_page" }
  ]
}

Les valeurs page_identifier (confirmation_page, tracking_page, returns_page) sont des constantes fixes définies par Rokt pour votre type d'intégration. Chaque marchand que vous enregistrez reçoit les mêmes identifiants ; ils ne sont pas des valeurs propres à chaque marchand. Stockez-les dans votre intégration SDK pour diriger les placements vers la bonne surface.

Votre code SDK lit cette chaîne et la passe dans selectPlacements:

await launcher.selectPlacements({
  identifier: "confirmation_page",   // ← from the response above
  attributes: { email: customer.email, /* ... */ }
});

Voir Intégration SDK pour la configuration complète du SDK.

Règles de validationLien direct vers Règles de validation

Le point de terminaison rejette les requêtes avec des erreurs descriptives 400 lorsque :

Une valeur surface n'est pas l'une des suivantes : confirmation / tracking / returns.
Une valeur layout_type n'est pas déclarée dans le préréglage de votre intégration. L'ensemble complet est Overlay et Embedded; votre intégration peut ne prendre en charge qu'un sous-ensemble. Le message d'erreur nomme les valeurs acceptées par votre préréglage.
La même surface apparaît plus d'une fois dans le tableau.
Le tableau pages est présent mais vide (omettez le champ pour utiliser le préréglage par défaut, ou incluez au moins une entrée).
Le préréglage de votre intégration n'a pas de LayoutSpecs configuré du tout. Contactez Rokt si vous voyez cette erreur.

Personnalisation de la mise en page d'un marchandLien direct vers Personnalisation de la mise en page d'un marchand

La réponse d'enregistrement contient un layout_id par page. Vous pouvez personnaliser une mise en page existante en envoyant un PATCH partiel à /v1/partnership/accounts/{account_id}/layouts/{layout_id}. Cinq jetons de thème sont exposés aujourd'hui :

primaryColor: accents interactifs (contrôles de progression / indicateurs)
backgroundColor: arrière-plans principal/extérieur et du conteneur de corps
textColor: couleurs du texte d'en-tête, de paragraphe et de pied de page
borderRadius: rayon des coins sur les conteneurs (0–24 px)
closeButtonColor: texte + bordure du bouton de fermeture (Overlay uniquement)

Les cinq champs sont facultatifs. Envoyez uniquement les clés que vous souhaitez modifier ; tout le reste reste tel quel. Rokt met également automatiquement à jour le modèle sous-jacent avec le dernier patch publié à chaque sauvegarde, de sorte que vos marchands bénéficient de petites corrections en amont sans aucune action de votre part.

remarque

Les remplacements de famille de polices ne sont pas encore exposés sur ce point de terminaison. Ils nécessitent que le partenaire télécharge d'abord la police sur le compte, ce qui n'a pas de point de terminaison accessible au partenaire aujourd'hui. Les polices personnalisées seront disponibles dans une version ultérieure avec ce flux de téléchargement. Si vous avez besoin d'une police non par défaut en attendant, contactez votre contact Rokt.

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
  }'

Pour une personnalisation plus poussée (nouvelles clés de thème, remplacements de texte), contactez votre contact Rokt.

Ajout de pages après l'enregistrementLien direct vers Ajout de pages après l'enregistrement

Besoin d'ajouter une surface à un marchand déjà enregistré (par exemple, ajouter une page tracking à un marchand qui n'avait configuré que confirmation)? POST /v1/partnership/accounts/{account_id}/pages accepte les mêmes entrées surface + layout_type que le tableau pages d'enregistrement:

remarque

La valeur pour platform_integration est l'identifiant de votre intégration (par exemple, your-integration-name); elle est la même pour chaque marchand que vous enregistrez. Rokt définit cela lors de la configuration de votre intégration.

curl -X POST https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/pages \
  -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>",
    "pages": [
      { "surface": "tracking", "layout_type": "Embedded" }
    ]
  }'

Chaque entrée crée une nouvelle Page et un Layout par marchand, lié au modèle canonique Rokt pour ce type de mise en page. La réponse porte la même structure pages que l'enregistrement. Stockez l'page_identifier retourné par surface et passez-le dans le SDK Web.

L'endpoint d'ajout de page d'aujourd'hui ne lie pas les nouvelles pages à l'ensemble de règles de ciblage de votre compte. Si votre intégration dépend de la liaison de l'ensemble de règles, configurez l'ensemble complet de surfaces lors de l'appel d'enregistrement initial.

Appeler deux fois pour la même surface renvoie 422 du gestionnaire sous-jacent (pas un propre 409); c'est une limitation de la version V1. Suivez quelles surfaces existent sur un compte à partir de la réponse d'enregistrement de votre pages[].page_identifier.

Changement des types de mise en pageLien direct vers Changement des types de mise en page

Si vous devez changer le type de mise en page pour une page existante (par exemple, lorsqu'un marchand souhaite passer des mises en page Overlay sur sa page de confirmation à des mises en page Embedded), appelez PUT /v1/partnership/accounts/{account_id}/pages/{page_id} où {page_id} est l'ID de la page que vous souhaitez mettre à jour. Le changement ne réinscrit pas le marchand et ne recrée pas la page. Le page_id est celui retourné dans pages[].page_id lors de l'inscription ou de la réponse d'ajout de pages :

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"
  }'

Les types de mise en page vers lesquels une page peut basculer sont le même ensemble que celui accepté par le préréglage de votre intégration lors de l'inscription et de l'ajout de pages. Si vous passez un layout_type qui n'est pas une valeur d'énumération reconnue (par exemple, une faute de frappe ou une chaîne inconnue), vous recevrez un 422 de la couche de validation d'entrée. Si layout_type est une valeur d'énumération valide mais non prise en charge pour la surface de cette page sur votre intégration, vous recevrez un 400 du serveur nommant les valeurs autorisées, le même contrat que l'inscription.

Trois choses que le changement ne modifie pas :

Le page_identifier reste le même. Votre code SDK continue de passer le même identifiant dans selectPlacements. Aucun changement côté marchand n'est nécessaire au-delà de l'élément d'ancrage (une mise en page Embedded nécessite toujours <div id="rokt-container"></div> sur la page du marchand).
Le ciblage de l'URL de la page reste le même. Le changement ne modifie que la manière dont les placements sont rendus, pas l'endroit où la page est déclenchée.
Les modifications de thème sont préservées. Les personnalisations appliquées via le point de terminaison PATCH de mise en page restent avec leur mise en page. 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.

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.

La réponse contient le layout_id maintenant actif sur la page. Utilisez cette valeur pour les modifications de thème ultérieures ; un layout_id que vous avez capturé avant le changement se réfère à la mise en page maintenant inactive :

{
  "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 point de terminaison renvoie 404 si le page_id (ou account_id) n'existe pas ou n'est pas accessible à votre compte gestionnaire, et 422 si la page n'est pas dans un état commutable. Chaque page_id retourné par l'enregistrement ou l'ajout de pages est commutable, donc les partenaires utilisant le flux standard ne devraient pas voir le cas 422.