Bonnes pratiques

L’ingestion de données dans le cloud de Braze vous permet d’établir une connexion directe entre votre entrepôt de données ou votre système de stockage de fichiers et Braze, afin de synchroniser les données pertinentes relatives aux utilisateurs ou aux catalogues. Lorsque vous synchronisez ces données avec Braze, vous pouvez les exploiter pour des cas d’utilisation tels que la personnalisation, le déclencheur ou la segmentation.

Comprendre la colonne UPDATED_AT

Lorsqu’une synchronisation s’exécute, Braze se connecte directement à votre instance d’entrepôt de données, récupère toutes les nouvelles données de la table spécifiée et met à jour les données correspondantes sur votre tableau de bord de Braze. Chaque fois que la synchronisation est exécutée, Braze reflète les données mises à jour.

Exemple : Synchronisation récurrente

Pour illustrer l’utilisation de UPDATED_AT dans une synchronisation CDI, prenez cet exemple de synchronisation récurrente pour la mise à jour des attributs d’un utilisateur :

• Sources de stockage de fichiers
  • Amazon S3

Types de données prises en charge

L’ingestion de données dans le nuage prend en charge les types de données suivants :

• Attributs de l’utilisateur, y compris :
  • Attributs personnalisés imbriqués
  • Tableaux d’objets
  • État des abonnements
• Événements personnalisés
• Événements d’achat
• Articles de catalogue
• Demandes de suppression d’un utilisateur

Vous pouvez mettre à jour les données de l’utilisateur par ID externe, alias d’utilisateur, ID Braze, e-mail ou numéro de téléphone. Vous pouvez supprimer des utilisateurs par ID externe, alias d’utilisateur ou ID Braze.

Qu’est-ce qui est synchronisé

Chaque fois qu’une synchronisation a lieu, Braze cherchera les lignes qui n’ont pas déjà été synchronisées. Nous le vérifions en utilisant la colonne UPDATED_AT dans votre table ou votre affichage. Braze sélectionne et importe toutes les lignes pour lesquelles UPDATED_AT est égal ou postérieur au dernier horodatage UPDATED_AT du dernier travail de synchronisation réussi.

Dans votre entrepôt de données, ajoutez les utilisateurs et les attributs suivants à votre table, en définissant l’heure UPDATED_AT sur le moment où vous ajoutez ces données :

Lors de la prochaine synchronisation planifiée, Braze synchronise toutes les lignes dont l’horodatage UPDATED_AT est égal ou postérieur à l’horodatage le plus récent dans les profils utilisateurs. Braze met à jour ou ajoute des champs, de sorte que vous ne devez pas synchroniser le profil utilisateur complet à chaque fois. Après la synchronisation, les profils utilisateurs reflètent les nouvelles mises à jour :

Synchronisation récurrente, deuxième passage le 20 juillet 2022 à 12h

Une ligne a été ajoutée, mais la valeur UPDATED_AT est antérieure à 2022-07-19 09:07:23 (stockée depuis la première exécution). Par conséquent, aucune de ces lignes ne sera synchronisée lors de cette exécution. Le dernier UPDATED_AT pour la synchronisation n’a pas été modifié par cette exécution et reste 2022-07-19 09:07:23.

Synchronisation récurrente, troisième passage le 21 juillet 2022 à 12 heures

Lors de ce troisième passage, une nouvelle ligne a été ajoutée. Maintenant, une ligne a une valeur UPDATED_AT postérieure à 2022-07-19 09:07:23, ce qui signifie qu’une seule ligne sera synchronisée. Le dernier UPDATED_AT est désormais défini comme 2022-07-21 08:30:00.

Utilisez un horodatage UTC pour la colonne UPDATED_AT

La colonne UPDATED_AT devrait être en UTC pour éviter les problèmes liés aux heures d’été. Utilisez de préférence des fonctions uniquement en UTC, telles que SYSDATE() plutôt que CURRENT_DATE() dès que possible.

Assurez-vous que l’heure de UPDATED_AT n’est pas la même que celle de votre synchronisation.

Votre synchronisation CDI peut contenir des données en double si l’un des champs UPDATED_AT est exactement à la même heure que le dernier horodatage UPDATED_AT de la précédente synchronisation réussie. En effet, CDI choisira une “limite inclusive” lorsqu’il identifiera une ligne qui se situe à la même heure que la synchronisation précédente, et fera en sorte que les lignes puissent se synchroniser. CDI ré-ingère ces lignes et crée des données en double.

Voici quelques suggestions pour éviter les données en double :

• Si vous mettez en place une synchronisation avec VIEW, n’utilisez pas CURRENT_TIMESTAMP comme valeur par défaut. Ceci entraînera la synchronisation de toutes les données chaque fois qu’elle s’effectue, car le champ UPDATED_AT sera évalué à chaque fois que nos requêtes sont lancées.
• Si vous avez des flux de données à très longue durée d’exécution ou des requêtes écrivant des données dans votre table source, évitez de les exécuter en même temps que la synchronisation ou évitez d’utiliser le même horodatage pour chaque ligne insérée.
• Utilisez une transaction pour écrire toutes les rangées qui ont le même horodatage.

Exemple : Gérer les mises à jour ultérieures

Cet exemple montre le processus général de synchronisation des données pour la première fois, puis la mise à jour des seules données changeantes (deltas) dans les mises à jour ultérieures. Supposons que nous ayons une table EXAMPLE_DATA contenant des données utilisateur. Le jour 1, il présente les valeurs suivantes :

Pour obtenir ces données dans le format attendu par CDI, vous pouvez exécuter la requête suivante :

1
2
3
4
5
6
7
8
9
10
11
12
SELECT
    CURRENT_TIMESTAMP AS UPDATED_AT,
    EXTERNAL_ID AS EXTERNAL_ID,
    TO_JSON(
        OBJECT_CONSTRUCT(
            'attribute_1', attribute_1,
            'attribute_2', attribute_2,
            'attribute_3', attribute_3,
            'attribute_4', attribute_4
        )
    ) AS PAYLOAD
FROM EXAMPLE_DATA;

Rien de tout cela n’ayant été synchronisé avec Braze auparavant, ajoutez tout cela à la table source pour CDI :

Une synchronisation s’exécute et Braze enregistre que vous avez synchronisé toutes les données disponibles jusqu’à “2023-03-16 15:00:00”. Ensuite, le matin du deuxième jour, vous avez un processus ETL qui s’exécute et certains champs de votre table d’utilisateurs sont mis à jour (en surbrillance) :

Vous devez maintenant ajouter uniquement les valeurs modifiées dans le tableau source CDI. Ces lignes peuvent être ajoutées plutôt que de mettre à jour les anciennes lignes. Ce tableau se présente désormais comme suit :

CDI ne synchronisera que les nouvelles lignes, de sorte que la prochaine synchronisation ne portera que sur les cinq dernières lignes.

Conseils supplémentaires

N’écrivez que les attributs nouveaux ou mis à jour pour limiter l’utilisation

Chaque fois qu’une synchronisation a lieu, Braze cherchera les lignes qui n’ont pas déjà été synchronisées. Nous le vérifions en utilisant la colonne UPDATED_AT dans votre table ou votre affichage. Braze sélectionne et importe toutes les lignes pour lesquelles UPDATED_AT est égal ou postérieur au dernier horodatage UPDATED_AT du dernier travail de synchronisation réussi, qu’elles soient ou non identiques à ce qui figure actuellement sur le profil utilisateur. Voilà pourquoi nous recommandons de ne synchroniser que les attributs que vous voulez ajouter ou mettre à jour.

L’utilisation des points de données est identique avec CDI qu’avec d’autres méthodes d’ingestion comme les API REST ou les SDK, il vous appartient donc de vous assurer que vous n’ajoutez que des attributs nouveaux ou mis à jour dans vos tables sources.

Séparer la colonne EXTERNAL_ID de la colonne PAYLOAD

L’objet PAYLOAD ne doit pas comporter d’ID externe ou d’autre type d’ID.

Supprimer un attribut

Vous pouvez lui attribuer la valeur null si vous souhaitez omettre un attribut dans le profil d’un utilisateur. Si vous désirez qu’un attribut reste inchangé, ne l’envoyez pas à Braze jusqu’à ce qu’il ait été mis à jour. Pour supprimer complètement un attribut, utilisez TO_JSON(OBJECT_CONSTRUCT_KEEP_NULL(...)).

Effectuer des mises à jour incrémentielles

Effectuez des mises à jour incrémentielles de vos données afin d’éviter les écrasements involontaires lors de mises à jour simultanées.

Dans l’exemple suivant, un utilisateur possède deux attributs :

• Couleur : “Vert”
• Taille : “Grand”

Braze reçoit alors simultanément les deux mises à jour suivantes pour cet utilisateur :

• Demande 1 : Changer la couleur en “Rouge”
• Demande 2 : Modifier la taille en “Moyen”

Comme la demande 1 survient en premier, les attributs de l’utilisateur sont mis à jour comme suit :

• Couleur : “Rouge”
• Taille : “Grand”

Cependant, lorsque la demande 2 se produit, Braze commence par les valeurs d’attribut originales (“Vert” et “Grand”), puis met à jour les attributs de l’utilisateur de la manière suivante :

• Couleur : “Vert”
• Taille : “Moyen”

Lorsque les demandes sont terminées, la demande 2 écrase la mise à jour de la demande 1. Il est donc préférable d’échelonner vos mises à jour afin d’éviter que les demandes ne soient écrasées.

Créer une chaîne de caractères JSON à partir d’une autre table

Si vous préférez stocker de manière interne chaque attribut dans sa propre colonne, vous devez convertir ces colonnes en chaîne de caractères JSON pour remplir la synchronisation avec Braze. Pour ce faire, vous pouvez utiliser une requête du type :

• snowflake
• redshift
• bigquery
• databricks
• microsoft fabric

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
CREATE TABLE "EXAMPLE_USER_DATA"
    (attribute_1 string,
     attribute_2 string,
     attribute_3 number,
     my_user_id string);

SELECT
    CURRENT_TIMESTAMP as UPDATED_AT,
    my_user_id as EXTERNAL_ID,
    TO_JSON(
        OBJECT_CONSTRUCT (
            'attribute_1',
            attribute_1,
            'attribute_2',
            attribute_2,
            'yet_another_attribute',
            attribute_3)
    )as PAYLOAD FROM "EXAMPLE_USER_DATA";

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
CREATE TABLE "EXAMPLE_USER_DATA"
    (attribute_1 string,
     attribute_2 string,
     attribute_3 number,
     my_user_id string);

SELECT
    CURRENT_TIMESTAMP as UPDATED_AT,
    my_user_id as EXTERNAL_ID,
    JSON_SERIALIZE(
        OBJECT (
            'attribute_1',
            attribute_1,
            'attribute_2',
            attribute_2,
            'yet_another_attribute',
            attribute_3)
    ) as PAYLOAD FROM "EXAMPLE_USER_DATA";

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
CREATE OR REPLACE TABLE BRAZE.EXAMPLE_USER_DATA (attribute_1 string,
     attribute_2 STRING,
     attribute_3 NUMERIC,
     my_user_id STRING);

SELECT
    CURRENT_TIMESTAMP as UPDATED_AT,
    my_user_id as EXTERNAL_ID,
    TO_JSON(
      STRUCT(
        'attribute_1' AS attribute_1,
        'attribute_2'AS attribute_2,
        'yet_another_attribute'AS attribute_3
      )
    ) as PAYLOAD 
  FROM BRAZE.EXAMPLE_USER_DATA;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
CREATE OR REPLACE TABLE BRAZE.EXAMPLE_USER_DATA (
    attribute_1 string,
    attribute_2 STRING,
    attribute_3 NUMERIC,
    my_user_id STRING
);

SELECT
    CURRENT_TIMESTAMP as UPDATED_AT,
    my_user_id as EXTERNAL_ID,
    TO_JSON(
      STRUCT(
        attribute_1,
        attribute_2,
        attribute_3
      )
    ) as PAYLOAD 
  FROM BRAZE.EXAMPLE_USER_DATA;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
CREATE TABLE [braze].[users] (
    attribute_1 VARCHAR,
    attribute_2 VARCHAR,
    attribute_3 VARCHAR,
    attribute_4 VARCHAR,
    user_id VARCHAR
)
GO

CREATE VIEW [braze].[user_update_example]
AS SELECT 
    user_id as EXTERNAL_ID,
    CURRENT_TIMESTAMP as UPDATED_AT,
    JSON_OBJECT('attribute_1':attribute_1, 'attribute_2':attribute_2, 'attribute_3':attribute_3, 'attribute_4':attribute_4) as PAYLOAD

FROM [braze].[users] ;

Utilisez l’horodatage UPDATED_AT

Nous utilisons l’horodatage UPDATED_AT pour suivre quelles données ont été synchronisées avec succès dans Braze. Si de nombreuses rangées sont écrites avec le même horodatage pendant qu’une synchronisation est en cours, ceci peut entraîner la synchronisation de données en double dans Braze. Voici quelques conseils pour éviter des données en double :

• Si vous mettez en place une synchronisation avec VIEW, n’utilisez pas CURRENT_TIMESTAMP comme valeur par défaut. Ceci entraînera la synchronisation de toutes les données chaque fois qu’elle s’effectue, car le champ UPDATED_AT sera évalué à chaque fois que nos requêtes sont lancées.
• Si vous avez des flux de données à très longue durée d’exécution ou des requêtes écrivant des données dans votre table source, évitez de les exécuter en même temps que la synchronisation ou évitez d’utiliser le même horodatage pour chaque ligne insérée.
• Utilisez une transaction pour écrire toutes les rangées qui ont le même horodatage.

Configuration de la table

Nous disposons d’un référentiel GitHub public permettant aux clients de partager des bonnes pratiques ou des extraits de code. Pour contribuer avec vos propres extraits de code, créez une requête d’extraction !

Formatage des données

Toutes les opérations possibles via l’endpoint de Braze /users/track sont prises en charge par l’ingestion de données dans le nuage, notamment la mise à jour des attributs personnalisés imbriqués, l’ajout d’un statut d’abonnement et la synchronisation d’événements personnalisés ou d’achats.

Les champs de la charge utile doivent respecter le même format que l’endpoint /users/track correspondant. Pour plus d’informations sur les exigences en matière de formatage, reportez-vous à ce qui suit :

Notez la nécessité de capturer les dates dans les attributs imbriqués.

• nested custom attributes
• event
• purchase
• subscription groups

1
2
3
4
5
6
7
8
9
10
11
12
{
      "most_played_song": {
        "song_name": "Solea",
        "artist_name": "Miles Davis",
        "album_name": "Sketches of Spain",
        "genre": "Jazz",
        "play_analytics": {
            "count": 1000,
            "top_10_listeners": true
        }
      }
}

1
2
3
4
5
6
7
8
9
{
    "app_id" : "your-app-id",
    "name" : "rented_movie",
    "time" : "2013-07-16T19:20:45+01:00",
    "properties": {
        "movie": "The Sad Egg",
        "director": "Dan Alexander"
    }
} 

1
2
3
4
5
6
7
8
9
10
11
12
{
    "app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
    "product_id" : "Completed Order",
    "currency" : "USD",
    "price" : 219.98,
    "time" : "2013-07-16T19:20:30+01:00",
    "properties" : {
        "products" : [ { "name": "Monitor", "category": "Gaming", "product_amount": 19.99, },
        { "name": "Gaming Keyboard", "category": "Gaming ", "product_amount": 199.99, }
        ]
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "subscription_groups" : [
        {
            "subscription_group_id": "subscription_group_identifier_1",
            "subscription_state": "unsubscribed"
        },
        {
            "subscription_group_id": "subscription_group_identifier_2",
            "subscription_state": "subscribed"
        },
        {
            "subscription_group_id": "subscription_group_identifier_3",
            "subscription_state": "subscribed"
        }
      ]
}

Éviter les délais d’attente pour les requêtes de l’entrepôt de données

Nous vous recommandons d’effectuer les requêtes dans un délai d’une heure afin d’optimiser les performances et d’éviter les erreurs potentielles. Si les requêtes dépassent ce délai, envisagez de revoir la configuration de votre entrepôt de données. L’optimisation des ressources allouées à votre entrepôt peut contribuer à améliorer la vitesse d’exécution des requêtes.

Limites du produit