Évaluer les événements en temps quasi réel grâce à la segmentation en flux continu

La segmentation en flux continu sur Adobe Experience Platform permet aux clients d’effectuer une segmentation en temps quasi réel tout en se concentrant sur la richesse des données. Avec la segmentation en flux continu, la qualification de segment se produit maintenant lorsque les données en flux continu entrent dans Platform, ce qui évite d’avoir à planifier et à exécuter des tâches de segmentation. Grâce à cette fonctionnalité, il est possible d’évaluer la plupart des règles de segmentation dès que les données sont transférées dans Platform, ce qui signifie que l’appartenance à un segment sera tenue à jour sans avoir à exécuter les tâches de segmentation planifiées.

Prise en main

Ce guide de développement nécessite une connaissance pratique des divers services Adobe Experience Platform impliqués dans la segmentation en flux continu. Avant de commencer ce tutoriel, veuillez consulter la documentation relative aux services suivants :

Les sections suivantes contiennent des informations supplémentaires nécessaires pour passer des appels à des API Platform.

Lecture d’exemples d’appels API

Ce guide de développement fournit des exemples d’appels API pour démontrer comment formater vos requêtes. Il s’agit notamment de chemins d’accès, d’en-têtes requis et de payloads de requêtes correctement formatés. L’exemple JSON renvoyé dans les réponses de l’API est également fourni. Pour plus d’informations sur les conventions utilisées dans la documentation pour les exemples d’appels d’API, voir la section concernant la lecture d’exemples d’appels d’API dans le guide de dépannage Experience Platform.

Collecte des valeurs des en-têtes requis

Pour lancer des appels aux API Platform, vous devez d’abord suivre le tutoriel d’authentification. Le tutoriel d’authentification fournit les valeurs de chacun des en-têtes requis dans tous les appels d’API Experience Platform, comme indiqué ci-dessous :

Dans Experience Platform, toutes les ressources sont isolées dans des sandbox virtuels spécifiques. Toutes les requêtes envoyées aux API Platform nécessitent un en-tête spécifiant le nom du sandbox dans lequel l’opération sera effectuée :

Toutes les requêtes contenant un payload (POST, PUT, PATCH) requièrent un en-tête supplémentaire :

Des en-têtes supplémentaires peuvent être nécessaires pour effectuer des requêtes spécifiques. Les en-têtes corrects sont présentés dans chacun des exemples de ce document. Accordez une attention particulière aux exemples de requêtes afin de vous assurer que tous les en-têtes requis sont inclus.

Types de requête permettant la segmentation par flux query-types

Pour qu’une définition de segment soit évaluée à l’aide de la segmentation par flux, la requête doit respecter les instructions suivantes.

Une définition de segment ne sera pas activée pour la segmentation en flux continu dans les scénarios suivants :

Veuillez noter que les instructions suivantes s’appliquent lors de la segmentation en flux continu :

Si une définition de segment est modifiée de sorte qu’elle ne répond plus aux critères de la segmentation en flux continu, elle passe automatiquement de « Diffusion en flux continu » à « Lots ».

De plus, la disqualification de segment, tout comme la qualification de segment, se produit en temps réel. Par conséquent, si un profil n’est plus admissible pour une définition de segment, il sera immédiatement non qualifié. Par exemple, si la définition de segment demande « Tous les utilisateurs et utilisatrices qui ont acheté des chaussures rouges au cours des trois dernières heures », tous les profils initialement qualifiés pour la définition de segment seront disqualifiés après trois heures.

Récupération de toutes les définitions de segment activées pour la segmentation par flux

Vous pouvez récupérer une liste de toutes vos définitions de segment activées pour la segmentation par flux au sein de votre organisation en envoyant une requête de GET au point de terminaison /segment/definitions.

Format d’API

Pour récupérer les définitions de segment activées pour la diffusion en continu, vous devez inclure le paramètre de requête evaluationInfo.continuous.enabled=true dans le chemin de requête.

GET /segment/definitions?evaluationInfo.continuous.enabled=true

Requête

curl -X GET \
  'https://platform.adobe.io/data/core/ups/segment/definitions?evaluationInfo.continuous.enabled=true' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Réponse

Une réponse réussie renvoie un tableau de définitions de segment de votre organisation activées pour la segmentation par flux.

{
    "segments": [
        {
            "id": "15063cb-2da8-4851-a2e2-bf59ddd2f004",
            "schema": {
                "name": "_xdm.context.profile"
            },
            "imsOrgId": "{ORG_ID}",
            "sandbox": {
                "sandboxId": "",
                "sandboxName": "",
                "type": "production",
                "default": true
            },
            "name": " People who are NOT on their homepage ",
            "expression": {
                "type": "PQL",
                "format": "pql/text",
                "value": "select var1 from xEvent where var1._experience.analytics.endUser.firstWeb.webPageDetails.isHomePage = false"
            },
            "evaluationInfo": {
                "batch": {
                    "enabled": false
                },
                "continuous": {
                    "enabled": true
                },
                "synchronous": {
                    "enabled": false
                }
            },
            "creationTime": 1572029711000,
            "updateEpoch": 1572029712000,
            "updateTime": 1572029712000
        },
        {
            "id": "f15063cb-2da8-4851-a2e2-bf59ddd2f004",
            "schema": {
                "name": "_xdm.context.profile"
            },
            "imsOrgId": "{ORG_ID}",
            "sandbox": {
                "sandboxId": "",
                "sandboxName": "",
                "type": "production",
                "default": true
            },
            "name": "Homepage_continuous",
            "description": "People who are on their homepage - continuous",
            "expression": {
                "type": "PQL",
                "format": "pql/text",
                "value": "select var1 from xEvent where var1._experience.analytics.endUser.firstWeb.webPageDetails.isHomePage = true"
            },
            "evaluationInfo": {
                "batch": {
                    "enabled": true
                },
                "continuous": {
                    "enabled": true
                },
                "synchronous": {
                    "enabled": false
                }
            },
            "creationTime": 1572021085000,
            "updateEpoch": 1572021086000,
            "updateTime": 1572021086000
        }
    ],
    "page": {
        "totalCount": 2,
        "totalPages": 1,
        "sortField": "creationTime",
        "sort": "desc",
        "pageSize": 2,
        "limit": 100
    },
    "link": {}
}

Création d’une définition de segment activée pour le flux

Une définition de segment sera automatiquement activée en continu si elle correspond à l’un des types de segmentation par flux répertoriés ci-dessus.

Format d’API

POST /segment/definitions

Requête

curl -X POST \
  https://platform.adobe.io/data/core/ups/segment/definitions \
  -H 'Authorization: Bearer {ACCESS_TOKEN}'  \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
    "schema": {
        "name": "_xdm.context.profile"
    },
    "name": "Homepage_continuous",
    "description": "People who are on their homepage - continuous",
    "expression": {
        "type": "PQL",
        "format": "pql/text",
        "value": "select var1 from xEvent where var1._experience.analytics.endUser.firstWeb.webPageDetails.isHomePage = true"
    },
    "evaluationInfo": {
        "batch": {
            "enabled": false
        },
        "continuous": {
            "enabled": true
        },
        "synchronous": {
            "enabled": false
        }
    }
}'

Réponse

Une réponse réussie renvoie les détails de la nouvelle définition de segment activée dans le flux.

{
    "id": "f15063cb-2da8-4851-a2e2-bf59ddd2f004",
    "schema": {
        "name": "_xdm.context.profile"
    },
    "imsOrgId": "{ORG_ID}",
    "sandbox": {
        "sandboxId": "{SANDBOX_ID}",
        "sandboxName": "{SANDBOX_NAME}",
        "type": "production",
        "default": true
    },
    "name": "Homepage_continuous",
    "description": "People who are on their homepage - continuous",
    "expression": {
        "type": "PQL",
        "format": "pql/text",
        "value": "select var1 from xEvent where var1._experience.analytics.endUser.firstWeb.webPageDetails.isHomePage = true"
    },
    "evaluationInfo": {
        "batch": {
            "enabled": false
        },
        "continuous": {
            "enabled": true,
                   },
        "synchronous": {
            "enabled": false
        }
    },
    "creationTime": 1572021085000,
    "updateEpoch": 1572021086000,
    "updateTime": 1572021086000
}

Activation de l’évaluation planifiée enable-scheduled-segmentation

Une fois l’évaluation par flux activée, une ligne de base doit être créée (après quoi la définition de segment sera toujours à jour). L’évaluation planifiée (également appelée segmentation planifiée) doit d’abord être activée pour que le système effectue automatiquement la mise en référence. Avec la segmentation planifiée, votre entreprise peut se conformer à un planning récurrent pour exécuter automatiquement des tâches d’exportation afin d’évaluer les définitions de segment.

Création d’un planning

En effectuant une requête POST sur le point d’entrée /config/schedules, vous pouvez créer un planning et inclure l’heure spécifique à laquelle le planning doit être déclenché.

Format d’API

POST /config/schedules

Requête

La requête suivante crée un planning en fonction des spécifications fournies dans le payload.

curl -X POST \
  https://platform.adobe.io/data/core/ups/config/schedules \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
        "name": "{SCHEDULE_NAME}",
        "type": "batch_segmentation",
        "properties": {
            "segments": ["*"]
        },
        "schedule": "0 0 1 * * ?",
        "state": "inactive"
        }'

Réponse

Une réponse réussie renvoie les détails du planning créé.

{
    "id": "cd585edf-962d-420d-94ad-3be03e619ac2",
    "imsOrgId": "{ORG_ID}",
    "sandbox": {
        "sandboxId": "e7e17720-c5bb-11e9-aafb-87c71c35cac8",
        "sandboxName": "prod",
        "type": "production",
        "default": true
    },
    "name": "{SCHEDULE_NAME}",
    "state": "inactive",
    "type": "batch_segmentation",
    "schedule": "0 0 1 * * ?",
    "properties": {
        "segments": [
            "*"
        ]
    },
    "createEpoch": 1568267948,
    "updateEpoch": 1568267948
}

Activation d’un planning

Par défaut, un planning est inactif lors de la création, sauf si la propriété state est définie sur active dans le corps de la requête de création (POST). Vous pouvez activer un planning (définissez state sur active) en effectuant une requête PATCH sur le point d’entrée /config/schedules et en incluant l’identifiant du planning dans le chemin.

Format d’API

POST /config/schedules/{SCHEDULE_ID}

Requête

La requête suivante utilise le format du correctif JSON pour mettre à jour l’état state du planning sur active.

curl -X POST \
  https://platform.adobe.io/data/core/ups/config/schedules/cd585edf-962d-420d-94ad-3be03e619ac2 \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '[
        {
          "op": "add",
          "path": "/state",
          "value": "active"
        }
      ]'

Réponse

Une mise à jour réussie renvoie un corps de réponse vide et un état HTTP 204 (No Content).

La même opération peut être utilisée pour désactiver un planning en remplaçant la « valeur » de la requête précédente par « inactif ».

Étapes suivantes

Maintenant que vous avez activé les définitions de segment nouvelles et existantes pour la segmentation par flux et activé la segmentation planifiée pour développer une ligne de base et effectuer des évaluations récurrentes, vous pouvez commencer à créer des définitions de segment activées pour la diffusion en continu pour votre organisation.

Pour savoir comment effectuer des actions similaires et utiliser des définitions de segment à l’aide de l’interface utilisateur de Adobe Experience Platform, consultez le guide d’utilisation du créateur de segments.

Annexe

La section suivante répertorie les questions fréquentes sur la segmentation en flux continu :

La « disqualification » de la segmentation en flux continu est-elle également effectuée en temps réel ?

Pour la plupart des instances, la disqualification de la segmentation en fux continu se produit en temps réel. Cependant, les définitions de segment par flux qui utilisent des segments de segments ne sont pas non admissibles en temps réel, mais non admissibles après 24 heures.

Sur quelles données la segmentation en flux continu fonctionne-t-elle ?

La segmentation en flux continu fonctionne sur toutes les données ingérées à l’aide d’une source en flux continu. Les segments ingérés à l’aide d’une source par lots seront évalués chaque nuit, même s’ils sont qualifiés pour la segmentation en flux continu. Les événements diffusés dans le système avec une date et une heure de plus de 24 heures seront traités dans le traitement par lots suivant.

Comment les définitions de segment sont-elles définies comme segmentation par lots ou par flux ?

Une définition de segment est définie comme une segmentation par lots ou par flux basée sur une combinaison de type de requête et de durée d’historique des événements. Vous trouverez une liste des définitions de segment qui seront évaluées en tant que segment en flux continu dans la section types de requête de segmentation en flux continu.

Notez que si un segment contient à la fois une expression inSegment et une chaîne d’événement unique directe, elle ne peut pas être qualifiée pour la segmentation en flux continu. Si vous souhaitez que cette définition de segment soit admissible pour la segmentation par flux, vous devez faire de la chaîne d’événement unique directe sa propre définition de segment.

Pourquoi le nombre de définitions de segment "total qualifié" continue-t-il à augmenter alors que le nombre sous "X derniers jours" reste à zéro dans la section des détails de la définition de segment ?

Le nombre total de définitions de segment qualifiées est tiré de la tâche de segmentation quotidienne, qui inclut les audiences admissibles aux définitions de segment par lot et en flux continu. Cette valeur s’affiche pour les définitions de segment par lot et en flux continu.

Le nombre sous « X derniers jours » comprend seulement les audiences qualifiées en segmentation en flux continu, et augmente seulement si vous avez diffusé des données en flux continu dans le système et qu’elles sont prises en compte dans cette définition de diffusion en flux continu. Cette valeur est uniquement affichée pour les définitions de segment en flux continu. Par conséquent, cette valeur may s’affiche comme 0 pour les définitions de segment par lot.

Par conséquent, si vous constatez que le nombre sous "X derniers jours" est nul et que le graphique linéaire signale également zéro, not a diffusé en continu dans le système les profils qui répondent aux critères de cette définition de segment.

Combien de temps faut-il pour qu’une définition de segment soit disponible ?

La disponibilité d’une définition de segment peut prendre jusqu’à une heure.

Existe-t-il des limites aux données diffusées en continu ?

Pour que les données en flux continu puissent être utilisées dans la segmentation par flux, il existe must un espacement entre les événements diffusés en continu. Si trop d’événements sont diffusés en continu dans la même seconde, Platform traite ces événements comme des données générées par des robots et ils seront ignorés. Pour respecter les bonnes pratiques, au moins doit s'écouler cinq secondes entre les données d'événement afin de s'assurer que les données sont correctement utilisées.