Personnaliser le flux pour les Content Cards

Un flux de Content Cards correspond à la séquence de Content Cards dans vos applications mobiles ou Web. Cet article traite de la configuration du moment où le flux est actualisé, de l’ordre des cartes, de la gestion de plusieurs flux et des messages d’erreur « flux vide ». Pour obtenir la liste complète des types de cartes de contenu, consultez À propos des Content Cards.

À propos du cycle de vie de la session

Une session désigne la période pendant laquelle le SDK Braze suit l’activité des utilisateurs dans votre application après son lancement. Vous pouvez également forcer une nouvelle session en appelant lachangeUser()méthode.

• web
• android
• swift

Par défaut, une session commence lorsque vous appelez pour la premièrebraze.openSession() fois . La session restera active pendant un maximum de30minutes d’inactivité (à moins que vous ne modifiiez le délai d’expiration par défaut de la session ou que l’utilisateur ne ferme l’application).

Remarque

Si vous avez configuré le rappel du cycle de ](/docs/fr/developer_guide/platform_integration_guides/android/initial_sdk_setup/android_sdk_integration/#step-4-tracking-user-sessions-in-android)vie des activités pour Android, Braze appellera automatiquementopenSession() etcloseSession()pour chaque activité de votre application.

Par défaut, une session commence lorsqueopenSession() est appelé pour la première fois. Si votre application passe en arrière-plan puis revient au premier plan, le SDK vérifiera si plus de 10 secondes se sont écoulées depuis le début de la session (à moins que vous ne modifiiez le délai d’expiration par défaut de la session). Dans ce cas, une nouvelle session débutera. Veuillez noter que si l’utilisateur ferme votre application alors qu’elle est en arrière-plan, les données de session risquent de ne pas être envoyées à Braze tant qu’il n’aura pas rouvert l’application.

Appeler necloseSession() mettra pas immédiatement fin à la session. Au lieu de cela, la session prendra fin après 10 secondes si l’utilisateur openSession()ne la relance pas en démarrant une autre activité.

Par défaut, une session commence lorsque vous appelez Braze.init(configuration:). Cela se produit lorsque le déclencheurUIApplicationWillEnterForegroundNotificationde la notification est activé, ce qui signifie que l’application est passée au premier plan.

Si votre application passe en arrière-plan, le UIApplicationDidEnterBackgroundNotificationdéclencheur est activé. L’application ne reste pas dans une session active lorsqu’elle est en arrière-plan. Lorsque votre application revient au premier plan, le SDK compare le temps écoulé depuis le début de la session au délai d’expiration de la session (à moins que vous ne modifiiez le délai d’expiration par défaut). Si le temps écoulé depuis le début de la session dépasse le délai d’expiration, une nouvelle session commence.

Actualisation du flux

Actualisation automatique

Par défaut, le flux de Content Cards s’actualise automatiquement dans les cas suivants :

• Une nouvelle session est démarrée
• Le flux de Content Cards par défaut est fermé puis rouvert après plus de 60 secondes écoulées depuis la dernière actualisation.

Conseil

Pour afficher dynamiquement des Content Cards à jour sans actualisation manuelle, sélectionnez À la première impression lors de la création de la carte. Ces cartes seront actualisées lorsqu’elles seront disponibles.

Distribution en temps réel

Braze envoie également les mises à jour de Content Cards à l’appareil dès qu’elles se produisent, via une connexion en direct que le SDK maintient pendant la session. Les utilisateurs n’ont pas besoin de démarrer une nouvelle session ni d’attendre une actualisation pour voir le changement.

La distribution en temps réel couvre les mises à jour suivantes :

• Un utilisateur devient éligible à une campagne de Content Cards pendant une session.
• Un utilisateur progresse vers une étape Content Card dans un Canvas.
• Une carte est retirée du flux d’un utilisateur.
• Une carte est envoyée via l’API, par exemple avec l’endpoint /messages/send, /campaigns/trigger/send, ou /canvas/trigger/send.

La distribution en temps réel nécessite les versions minimales de SDK suivantes :

Sur les versions antérieures du SDK, les cartes continuent d’arriver au démarrage de la session et lors de l’actualisation.

Actualisation manuelle

Pour actualiser manuellement le flux à un moment précis :

• web
• android
• swift

1
2
3
4
5
import * as braze from "@braze/web-sdk";

function refresh() {
  braze.requestContentCardsRefresh();
}

1
Braze.getInstance(context).requestContentCardsRefresh();

1
Braze.getInstance(context).requestContentCardsRefresh()

1
2
3
AppDelegate.braze?.contentCards.requestRefresh { result in
  // Implement completion handler
}

1
let contentCards = await AppDelegate.braze?.contentCards.requestRefresh()

1
2
3
[AppDelegate.braze.contentCards requestRefreshWithCompletion:^(NSArray<BRZContentCardRaw *> * contentCards, NSError * error) {
  // Implement completion handler
}];

Synchronisation complète et synchronisation partielle

Le SDK Braze utilise deux types de synchronisation lors de la récupération des Content Cards depuis le serveur :

• Synchronisation complète : récupère toutes les Content Cards auxquelles un utilisateur est éligible. Les synchronisations complètes se produisent automatiquement tous les 7 jours ou chaque fois que changeUser() est appelé.
• Synchronisation partielle : récupère uniquement les nouvelles Content Cards depuis la dernière requête. Si l’utilisateur n’est éligible à aucune nouvelle carte, la réponse renvoie zéro carte. Les synchronisations partielles se produisent chaque fois que requestContentCardsRefresh() est appelé (sauf si 7 jours se sont écoulés depuis la dernière synchronisation complète, auquel cas une synchronisation complète est déclenchée à la place).

Les synchronisations partielles réduisent la charge serveur et la consommation de batterie de l’appareil. Les Content Cards déjà reçues sont stockées localement dans le SDK, de sorte que les utilisateurs continueront à voir leurs cartes disponibles même lorsqu’une synchronisation partielle ne renvoie aucune nouvelle carte.

Limitation du débit

Braze utilise un algorithme de compartiment à jetons pour appliquer les limitations de débit suivantes :

• Jusqu’à 5 appels d’actualisation par appareil, partagés entre les utilisateurs et les appels à openSession()
• Après avoir atteint la limite, un nouvel appel devient disponible toutes les 180 secondes (3 minutes)
• Le système conserve jusqu’à cinq appels que vous pouvez utiliser à tout moment
• subscribeToContentCards() renverra toujours les cartes en cache même en cas de limitation du débit

Important

Le SDK Braze applique également des limitations de débit pour des raisons de performance et de fiabilité. Gardez cela à l’esprit lors de l’exécution de tests automatisés ou de contrôles qualité manuels. Consultez les limitations de débit du SDK Braze pour plus d’informations.

Personnalisation de l’ordre d’affichage des cartes

Vous pouvez modifier l’ordre dans lequel vos Content Cards sont affichées. Cela vous permet d’affiner l’expérience utilisateur en priorisant certains types de contenu, comme les promotions à durée limitée.

• web
• android
• swift

Personnalisez l’ordre d’affichage des Content Cards dans votre flux en utilisant le paramètre filterFunction de showContentCards():. Par exemple :

1
2
3
braze.showContentCards(null, (cards) => {
  return sortBrazeCards(cards); // Where sortBrazeCards is your sorting function that returns the sorted card array
});

• android view controller
• jetpack compose

Le ContentCardsFragment s’appuie sur un IContentCardsUpdateHandler pour gérer tout tri ou toute modification des Content Cards avant leur affichage dans le flux. Un gestionnaire de mise à jour personnalisé peut être défini via setContentCardUpdateHandler sur votre ContentCardsFragment.

Voici le IContentCardsUpdateHandler par défaut, qui peut servir de point de départ pour la personnalisation :

Afficher l’exemple Java

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
public class DefaultContentCardsUpdateHandler implements IContentCardsUpdateHandler {

  // Interface that must be implemented and provided as a public CREATOR
  // field that generates instances of your Parcelable class from a Parcel.
  public static final Parcelable.Creator<DefaultContentCardsUpdateHandler> CREATOR = new Parcelable.Creator<DefaultContentCardsUpdateHandler>() {
    public DefaultContentCardsUpdateHandler createFromParcel(Parcel in) {
      return new DefaultContentCardsUpdateHandler();
    }

    public DefaultContentCardsUpdateHandler[] newArray(int size) {
      return new DefaultContentCardsUpdateHandler[size];
    }
  };

  @Override
  public List<Card> handleCardUpdate(ContentCardsUpdatedEvent event) {
    List<Card> sortedCards = event.getAllCards();
    // Sort by pinned, then by the 'updated' timestamp descending
    // Pinned before non-pinned
    Collections.sort(sortedCards, new Comparator<Card>() {
      @Override
      public int compare(Card cardA, Card cardB) {
        // A displays above B
        if (cardA.getIsPinned() && !cardB.getIsPinned()) {
          return -1;
        }

        // B displays above A
        if (!cardA.getIsPinned() && cardB.getIsPinned()) {
          return 1;
        }

        // At this point, both A & B are pinned or both A & B are non-pinned
        // A displays above B since A is newer
        if (cardA.getUpdated() > cardB.getUpdated()) {
          return -1;
        }

        // B displays above A since A is newer
        if (cardA.getUpdated() < cardB.getUpdated()) {
          return 1;
        }

        // At this point, every sortable field matches so keep the natural ordering
        return 0;
      }
    });

    return sortedCards;
  }

  // Parcelable interface method
  @Override
  public int describeContents() {
    return 0;
  }

  // Parcelable interface method
  @Override
  public void writeToParcel(Parcel dest, int flags) {
    // No state is kept in this class so the parcel is left unmodified
  }
}

Afficher l’exemple Kotlin

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
class DefaultContentCardsUpdateHandler : IContentCardsUpdateHandler {
  override fun handleCardUpdate(event: ContentCardsUpdatedEvent): List<Card> {
    val sortedCards = event.allCards
    // Sort by pinned, then by the 'updated' timestamp descending
    // Pinned before non-pinned
    sortedCards.sortWith(Comparator sort@{ cardA: Card, cardB: Card ->
      // A displays above B
      if (cardA.isPinned && !cardB.isPinned) {
        return@sort -1
      }

      // B displays above A
      if (!cardA.isPinned && cardB.isPinned) {
        return@sort 1
      }

      // At this point, both A & B are pinned or both A & B are non-pinned
      // A displays above B since A is newer
      if (cardA.updated > cardB.updated) {
        return@sort -1
      }

      // B displays above A since A is newer
      if (cardA.updated < cardB.updated) {
        return@sort 1
      }
      0
    })
    return sortedCards
  }

  // Parcelable interface method
  override fun describeContents(): Int {
    return 0
  }

  // Parcelable interface method
  override fun writeToParcel(dest: Parcel, flags: Int) {
    // No state is kept in this class so the parcel is left unmodified
  }

  companion object {
    // Interface that must be implemented and provided as a public CREATOR
    // field that generates instances of your Parcelable class from a Parcel.
    val CREATOR: Parcelable.Creator<DefaultContentCardsUpdateHandler?> = object : Parcelable.Creator<DefaultContentCardsUpdateHandler?> {
      override fun createFromParcel(`in`: Parcel): DefaultContentCardsUpdateHandler? {
        return DefaultContentCardsUpdateHandler()
      }

      override fun newArray(size: Int): Array<DefaultContentCardsUpdateHandler?> {
        return arrayOfNulls(size)
      }
    }
  }
}

Conseil

Le code source de ContentCardsFragment est disponible sur GitHub.

Pour filtrer et trier les Content Cards dans Jetpack Compose, définissez le paramètre cardUpdateHandler. Par exemple :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
ContentCardsList(
    cardUpdateHandler = {
        it.sortedWith { cardA, cardB ->
            // A displays above B
            if (cardA.isPinned && !cardB.isPinned) {
                return@sortedWith -1
            }
            // B displays above A
            if (!cardA.isPinned && cardB.isPinned) {
                return@sortedWith 1
            }
            // At this point, both A & B are pinned or both A & B are non-pinned
            // A displays above B since A is newer
            if (cardA.updated > cardB.updated) {
                return@sortedWith -1
            }
            // B displays above A since A is newer
            if (cardA.updated < cardB.updated) {
                return@sortedWith 1
            }
            0
        }
    }
)

• swift
• objective-c

Personnalisez l’ordre du flux de cartes en modifiant directement la variable statique Attributes.defaults.

1
2
3
4
5
6
7
8
9
10
11
12
13
var attributes = BrazeContentCardUI.ViewController.Attributes.defaults
attributes.transform = { cards in
    cards.sorted {
        if $0.pinned && !$1.pinned {
            return true
        } else if !$0.pinned && $1.pinned {
            return false
        } else {
            return $0.createdAt > $1.createdAt
        }
    }
}
let viewController = BrazeContentCardUI.ViewController(braze: AppDelegate.braze, attributes: attributes)

La personnalisation via BrazeContentCardUI.ViewController.Attributes n’est pas disponible en Objective-C.

Personnalisation du message « flux vide »

Lorsqu’un utilisateur ne remplit les conditions d’aucune Content Card, le SDK affiche un message d’erreur de « flux vide » indiquant : « We have no updates. Please check again later. » Vous pouvez personnaliser ce message d’erreur de « flux vide » de manière similaire à l’exemple suivant :

• web
• android
• swift

Le SDK Web ne prend pas en charge le remplacement programmatique du texte de « flux vide ». Vous pouvez choisir de le remplacer à chaque affichage du flux, mais cela n’est pas recommandé car le flux peut mettre un certain temps à s’actualiser et le texte de flux vide ne s’affichera pas immédiatement.

• android view system
• jetpack compose

Si le ContentCardsFragment détermine que l’utilisateur ne remplit les conditions d’aucune Content Card, il affiche le message d’erreur de flux vide.

Un adaptateur spécial, le EmptyContentCardsAdapter, remplace le ContentCardAdapter standard pour afficher ce message d’erreur. Pour définir le message personnalisé, remplacez la ressource de chaîne com_braze_feed_empty.

Le style utilisé pour afficher ce message se trouve via Braze.ContentCardsDisplay.Empty et est reproduit dans l’extrait de code suivant :

1
2
3
4
5
6
7
8
9
<style name="Braze.ContentCardsDisplay.Empty">
  <item name="android:lineSpacingExtra">1.5dp</item>
  <item name="android:text">@string/com_braze_feed_empty</item>
  <item name="android:textColor">@color/com_braze_content_card_empty_text_color</item>
  <item name="android:textSize">18.0sp</item>
  <item name="android:gravity">center</item>
  <item name="android:layout_height">match_parent</item>
  <item name="android:layout_width">match_parent</item>
</style>

Pour en savoir plus sur la personnalisation des éléments de style des Content Cards, consultez Personnalisation du style.

Pour personnaliser le message d’erreur de « flux vide » avec Jetpack Compose, vous pouvez passer un emptyString à ContentCardsList. Vous pouvez également passer emptyTextStyle à ContentCardListStyling pour personnaliser davantage ce message.

1
2
3
4
5
6
ContentCardsList(
    emptyString = "No messages today",
    style = ContentCardListStyling(
        emptyTextStyle = TextStyle(...)
    )
)

Si vous disposez d’un Composable que vous souhaitez afficher à la place, vous pouvez passer emptyComposable à ContentCardsList. Si emptyComposable est spécifié, le emptyString ne sera pas utilisé.

1
2
3
4
5
6
7
8
ContentCardsList(
    emptyComposable = {
        Image(
            painter = painterResource(id = R.drawable.noMessages),
            contentDescription = "No messages"
        )
    }
)

• swift
• objective-c

Personnalisez l’état vide du contrôleur de vue en définissant les Attributes associés.

1
2
3
4
var attributes = BrazeContentCardUI.ViewController.Attributes.defaults
attributes.emptyStateMessage = "This is a custom empty state message"
attributes.emptyStateMessageFont = .preferredFont(forTextStyle: .title1)
attributes.emptyStateMessageColor = .secondaryLabel

Modifiez le texte qui s’affiche automatiquement dans les flux de Content Cards vides en redéfinissant les chaînes localisables de Content Cards dans le fichier ContentCardsLocalizable.strings de votre application.

Remarque

Si vous souhaitez mettre à jour ce message dans différentes langues, recherchez la langue correspondante dans la structure du dossier Resources avec la chaîne ContentCardsLocalizable.strings.

Implémenter plusieurs flux

Les Content Cards peuvent être filtrées dans votre application afin que seules des cartes spécifiques soient affichées, ce qui vous permet d’avoir plusieurs flux de Content Cards pour différents cas d’usage. Par exemple, vous pouvez maintenir à la fois un flux transactionnel et un flux marketing. Pour cela, créez différentes catégories de Content Cards en définissant des paires clé-valeur dans le tableau de bord de Braze. Ensuite, créez des flux dans votre application ou votre site qui traitent ces types de Content Cards différemment, en filtrant certains types et en affichant les autres.

Étape 1 : Définir des paires clé-valeur sur les cartes

Lors de la création d’une campagne de Content Cards, définissez des données de paires clé-valeur sur chaque carte. Vous utiliserez cette paire clé-valeur pour catégoriser les cartes. Les paires clé-valeur sont stockées dans la propriété extras du modèle de données de la carte.

Pour cet exemple, nous allons définir une paire clé-valeur avec la clé feed_type qui désignera dans quel flux de Content Cards la carte doit être affichée. La valeur sera celle de vos flux personnalisés, comme home_screen ou marketing.

Étape 2 : Filtrer les Content Cards

Une fois les paires clé-valeur assignées, créez un flux avec une logique qui affichera les cartes souhaitées et filtrera les cartes des autres types. Dans cet exemple, nous n’afficherons que les cartes avec une paire clé-valeur correspondante feed_type: "Transactional".

• web
• android
• swift

1
2
3
4
5
6
7
8
9
/**
 * @param {String} feed_type - value of the "feed_type" KVP to filter
 */
function showCardsByFeedType(feed_type) {
  braze.showContentCards(null, function(cards) {
    return cards.filter((card) => card.extras["feed_type"] === feed_type);
  });
}

1
2
3
4
// show the "Transactional" feed when this button is clicked
document.getElementById("show-transactional-feed").onclick = function() {
  showCardsByFeedType("Transactional");
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
private IContentCardsUpdateHandler getUpdateHandlerForFeedType(final String desiredFeedType) {
  return new IContentCardsUpdateHandler() {
    @Override
    public List<Card> handleCardUpdate(ContentCardsUpdatedEvent event) {
      // Use the default card update handler for a first
      // pass at sorting the cards. This is not required
      // but is done for convenience.
      final List<Card> cards = new DefaultContentCardsUpdateHandler().handleCardUpdate(event);

      final Iterator<Card> cardIterator = cards.iterator();
      while (cardIterator.hasNext()) {
        final Card card = cardIterator.next();

        // Make sure the card has our custom KVP
        // from the dashboard with the key "feed_type"
        if (card.getExtras().containsKey("feed_type")) {
          final String feedType = card.getExtras().get("feed_type");
          if (!desiredFeedType.equals(feedType)) {
            // The card has a feed type, but it doesn't match
            // our desired feed type, remove it.
            cardIterator.remove();
          }
        } else {
          // The card doesn't have a feed
          // type at all, remove it
          cardIterator.remove();
        }
      }

      // At this point, all of the cards in this list have
      // a feed type that explicitly matches the value we put
      // in the dashboard.
      return cards;
    }
  };
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
private fun getUpdateHandlerForFeedType(desiredFeedType: String): IContentCardsUpdateHandler {
  return IContentCardsUpdateHandler { event ->
    // Use the default card update handler for a first
    // pass at sorting the cards. This is not required
    // but is done for convenience.
    val cards = DefaultContentCardsUpdateHandler().handleCardUpdate(event)

    val cardIterator = cards.iterator()
    while (cardIterator.hasNext()) {
      val card = cardIterator.next()

      // Make sure the card has our custom KVP
      // from the dashboard with the key "feed_type"
      if (card.extras.containsKey("feed_type")) {
        val feedType = card.extras["feed_type"]
        if (desiredFeedType != feedType) {
          // The card has a feed type, but it doesn't match
          // our desired feed type, remove it.
          cardIterator.remove()
        }
      } else {
        // The card doesn't have a feed
        // type at all, remove it
        cardIterator.remove()
      }
    }

    // At this point, all of the cards in this list have
    // a feed type that explicitly matches the value we put
    // in the dashboard.
    cards
  }
}

1
2
3
// We want a Content Cards feed that only shows "Transactional" cards.
ContentCardsFragment customContentCardsFragment = new ContentCardsFragment();
customContentCardsFragment.setContentCardUpdateHandler(getUpdateHandlerForFeedType("Transactional"));

1
2
3
// We want a Content Cards feed that only shows "Transactional" cards.
val customContentCardsFragment = ContentCardsFragment()
customContentCardsFragment.contentCardUpdateHandler = getUpdateHandlerForFeedType("Transactional")

1
2
3
4
5
6
7
ContentCardsList(
     cardUpdateHandler = {
         it.filter { card ->
             card.extras["feed_type"] == "Transactional"
         }
     }
 )

1
2
// Filter cards by the `Transactional` feed type based on your key-value pair.
let transactionalCards = cards.filter { $0.extras["feed_type"] as? String == "Transactional" }

1
2
3
4
5
6
7
var attributes = BrazeContentCardUI.ViewController.Attributes.defaults
attributes.transform = { cards in
  cards.filter { $0.extras["feed_type"] as? String == "Transactional" }
}

// Pass your attributes containing the transformed cards to the Content Card UI.
let viewController = BrazeContentCardUI.ViewController(braze: AppDelegate.braze, attributes: attributes)

1
2
3
4
5
6
7
// Filter cards by the `Transactional` feed type based on your key-value pair.
NSMutableArray<BRZContentCardRaw *> *transactionalCards = [[NSMutableArray alloc] init];
for (BRZContentCardRaw *card in AppDelegate.braze.contentCards.cards) {
  if ([card.extras[@"feed_type"] isEqualToString:@"Transactional"]) {
    [transactionalCards addObject:card];
  }
}