Den Feed für Content Cards anpassen

Ein Content-Card-Feed ist die Abfolge von Content Cards in Ihren Mobil- oder Internet-Apps. Dieser Artikel befasst sich mit der Konfiguration, wann der Feed aktualisiert wird, der Reihenfolge der Karten, der Verwaltung mehrerer Feeds und den Fehlermeldungen „leerer Feed“. Eine vollständige Liste der Content-Card-Typen finden Sie unter Über Content Cards.

Über den Lebenszyklus einer Sitzung

Eine Sitzung bezeichnet den Zeitraum, in dem das Braze SDK die Aktivitäten von Nutzer:innen in Ihrer App nach deren Start verfolgt. Sie können auch eine neue Sitzung erzwingen, indem Sie die Methode changeUser() aufrufen.

• web
• android
• swift

Standardmäßig beginnt eine Sitzung, wenn Sie braze.openSession() zum ersten Mal aufrufen. Die Sitzung bleibt bis zu 30 Minuten bei Inaktivität aktiv (es sei denn, Sie ändern den Standard-Timeout für die Sitzung) oder die Nutzer:innen schließen die App.

Hinweis

Wenn Sie den Aktivitätslebenszyklus-Callback für Android eingerichtet haben, ruft Braze automatisch openSession() und closeSession() für jede Aktivität in Ihrer App auf.

Standardmäßig wird eine Sitzung gestartet, wenn openSession() zum ersten Mal aufgerufen wird. Wenn Ihre App in den Hintergrund wechselt und anschließend wieder in den Vordergrund zurückkehrt, überprüft das SDK, ob seit Beginn der Sitzung mehr als 10 Sekunden vergangen sind (es sei denn, Sie ändern den Standard-Timeout für die Sitzung). Falls ja, beginnt eine neue Sitzung. Beachten Sie, dass Sitzungsdaten möglicherweise erst dann an Braze gesendet werden, wenn Nutzer:innen die App erneut öffnen, falls sie die App schließen, während diese im Hintergrund läuft.

Der Aufruf von closeSession() beendet die Sitzung nicht sofort. Stattdessen wird die Sitzung nach 10 Sekunden beendet, wenn openSession() nicht erneut aufgerufen wird, weil Nutzer:innen eine andere Aktivität starten.

Standardmäßig beginnt eine Sitzung, wenn Sie Braze.init(configuration:) aufrufen. Dies geschieht, wenn die Benachrichtigung UIApplicationWillEnterForegroundNotification ausgelöst wird, was bedeutet, dass die App in den Vordergrund gewechselt ist.

Wenn Ihre App in den Hintergrund wechselt, wird UIApplicationDidEnterBackgroundNotification ausgelöst. Die App bleibt im Hintergrund nicht in einer aktiven Sitzung. Wenn Ihre App wieder in den Vordergrund rückt, vergleicht das SDK die seit Beginn der Sitzung verstrichene Zeit mit dem Sitzungs-Timeout (es sei denn, Sie ändern den Standard-Timeout für die Sitzung). Wenn die seit Beginn der Sitzung verstrichene Zeit den Timeout überschreitet, wird eine neue Sitzung gestartet.

Feed aktualisieren

Automatische Aktualisierung

Standardmäßig wird der Content-Card-Feed automatisch aktualisiert, wenn:

• Eine neue Session gestartet wird
• Der Standard-Content-Card-Feed geschlossen und erneut geöffnet wird, nachdem seit der letzten Aktualisierung mehr als 60 Sekunden vergangen sind.

Tipp

Um aktuelle Content Cards dynamisch anzuzeigen, ohne sie manuell zu aktualisieren, wählen Sie bei der Erstellung der Karte Bei erster Impression aus. Diese Karten werden aktualisiert, sobald sie verfügbar sind.

Zustellung in Realtime

Braze sendet Content-Card-Updates außerdem an das Gerät, sobald sie auftreten – über eine Live-Verbindung, die das SDK während der Session aufrechterhält. Nutzer:innen müssen weder eine neue Session starten noch auf eine Aktualisierung warten, um die Änderung zu sehen. Die Zustellung in Realtime funktioniert sowohl für Standard- als auch für angepasste Content-Card-Feeds.

Die Zustellung in Realtime umfasst die folgenden Updates:

• Nutzer:innen werden während einer Session für eine Content-Card-Kampagne berechtigt.
• Nutzer:innen gelangen zu einem Content-Card-Schritt in einem Canvas.
• Eine Karte wird aus dem Feed von Nutzer:innen entfernt.
• Eine Karte wird über die API gesendet, beispielsweise mit dem Endpunkt /messages/send, /campaigns/trigger/send oder /canvas/trigger/send.

Für die Zustellung in Realtime sind die folgenden SDK-Mindestversionen erforderlich:

Bei früheren SDK-Versionen werden Karten weiterhin beim Session-Start und bei einer Aktualisierung zugestellt.

Manuelle Aktualisierung

So aktualisieren Sie den Feed manuell zu einem bestimmten Zeitpunkt:

• 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
}];

Vollständige vs. teilweise Synchronisierung

Das Braze SDK verwendet beim Abrufen von Content Cards vom Server zwei Arten der Synchronisierung:

• Vollständige Synchronisierung: Ruft alle Content Cards ab, für die Nutzer:innen berechtigt sind. Vollständige Synchronisierungen erfolgen automatisch alle 7 Tage oder immer dann, wenn changeUser() aufgerufen wird.
• Teilweise Synchronisierung: Ruft nur die seit der letzten Anfrage neuen Content Cards ab. Wenn Nutzer:innen für keine neuen Karten berechtigt sind, gibt die Antwort null Karten zurück. Teilweise Synchronisierungen erfolgen bei jedem Aufruf von requestContentCardsRefresh() (es sei denn, seit der letzten vollständigen Synchronisierung sind 7 Tage vergangen – in diesem Fall wird stattdessen eine vollständige Synchronisierung getriggert).

Teilweise Synchronisierungen verringern die Serverlast und den Akkuverbrauch des Geräts. Bereits empfangene Content Cards werden lokal im SDK gespeichert, sodass Nutzer:innen ihre verfügbaren Karten weiterhin sehen, auch wenn eine teilweise Synchronisierung null neue Karten zurückgibt.

Rate-Limit

Braze verwendet einen Token-Bucket-Algorithmus, um die folgenden Rate-Limits durchzusetzen:

• Bis zu 5 Aktualisierungsaufrufe pro Gerät, die von allen Nutzer:innen und Aufrufen von openSession() gemeinsam genutzt werden
• Nach Erreichen des Limits wird alle 180 Sekunden (3 Minuten) ein neuer Aufruf verfügbar
• Das System hält bis zu fünf Aufrufe vor, die Sie jederzeit nutzen können
• subscribeToContentCards() gibt auch bei Erreichen des Rate-Limits weiterhin zwischengespeicherte Karten zurück

Wichtig

Das Braze SDK wendet außerdem Rate-Limits für Performance und Zuverlässigkeit an. Berücksichtigen Sie dies bei automatisierten Tests oder bei manuellen QA-Prüfungen. Weitere Informationen finden Sie unter Rate-Limits des Braze SDK.

Angepasste Reihenfolge der angezeigten Karten

Sie können die Reihenfolge ändern, in der Ihre Content Cards angezeigt werden. So können Sie das Nutzererlebnis gezielt optimieren, indem Sie bestimmte Arten von Inhalten priorisieren, z. B. zeitkritische Aktionen.

• web
• android
• swift

Passen Sie die Anzeigereihenfolge der Content Cards in Ihrem Feed über den Parameter filterFunction von showContentCards(): an. Zum Beispiel:

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

Das ContentCardsFragment nutzt einen IContentCardsUpdateHandler, um Content Cards zu sortieren oder zu verändern, bevor sie im Feed angezeigt werden. Einen angepassten Update-Handler können Sie über setContentCardUpdateHandler in Ihrem ContentCardsFragment festlegen.

Im Folgenden sehen Sie den standardmäßigen IContentCardsUpdateHandler, den Sie als Ausgangspunkt für Ihre Anpassungen verwenden können:

Show Java example

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

Show Kotlin example

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

Tipp

Den Quellcode von ContentCardsFragment finden Sie auf GitHub.

Um Content Cards in Jetpack Compose zu filtern und zu sortieren, legen Sie den Parameter cardUpdateHandler fest. Zum Beispiel:

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

Passen Sie die Reihenfolge des Karten-Feeds an, indem Sie die statische Variable Attributes.defaults direkt ändern.

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)

Die Anpassung über BrazeContentCardUI.ViewController.Attributes ist in Objective-C nicht verfügbar.

Die Nachricht „Leerer Feed“ anpassen

Wenn Nutzer:innen für keine Content Cards infrage kommen, zeigt das SDK die Fehlermeldung „Leerer Feed“ mit dem Text „We have no updates. Please check again later.“ an. Sie können diese Fehlermeldung beispielsweise wie folgt anpassen:

• web
• android
• swift

Das Web SDK unterstützt kein programmatisches Ersetzen des Textes für einen leeren Feed. Sie können den Text zwar bei jeder Anzeige des Feeds ersetzen, das empfehlen wir jedoch nicht: Die Aktualisierung des Feeds kann etwas dauern, sodass der Text für den leeren Feed nicht sofort angezeigt wird.

• android view system
• jetpack compose

Wenn das ContentCardsFragment feststellt, dass Nutzer:innen für keine Content Cards infrage kommen, zeigt es die Fehlermeldung für den leeren Feed an.

Ein spezieller Adapter, der EmptyContentCardsAdapter, ersetzt den Standard-ContentCardAdapter, um diese Fehlermeldung anzuzeigen. Um die angepasste Nachricht selbst festzulegen, überschreiben Sie die String-Ressource com_braze_feed_empty.

Den Stil, mit dem diese Nachricht angezeigt wird, finden Sie unter Braze.ContentCardsDisplay.Empty. Er ist im folgenden Code-Snippet wiedergegeben:

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>

Weitere Informationen zum Anpassen der Stilelemente von Content-Cards finden Sie unter Stil anpassen.

Um die Fehlermeldung „Leerer Feed“ mit Jetpack Compose anzupassen, können Sie einen emptyString an ContentCardsList übergeben. Zusätzlich können Sie emptyTextStyle an ContentCardListStyling übergeben, um diese Nachricht weiter anzupassen.

1
2
3
4
5
6

ContentCardsList(
    emptyString = "No messages today",
    style = ContentCardListStyling(
        emptyTextStyle = TextStyle(...)
    )
)

Wenn Sie stattdessen ein Composable anzeigen möchten, können Sie emptyComposable an ContentCardsList übergeben. Wenn emptyComposable angegeben ist, wird emptyString nicht verwendet.

1
2
3
4
5
6
7
8

ContentCardsList(
    emptyComposable = {
        Image(
            painter = painterResource(id = R.drawable.noMessages),
            contentDescription = "No messages"
        )
    }
)

• swift
• objective-c

Passen Sie den leeren Zustand des View-Controllers an, indem Sie die entsprechenden Attributes festlegen.

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

Ändern Sie den Text, der in leeren Content-Card-Feeds automatisch angezeigt wird, indem Sie die lokalisierbaren Content-Card-Strings in der Datei ContentCardsLocalizable.strings Ihrer App neu definieren.

Hinweis

Wenn Sie diese Nachricht für verschiedene Sprachen aktualisieren möchten, suchen Sie die entsprechende Sprache in der Ordnerstruktur „Resources“ mit dem String ContentCardsLocalizable.strings.

Mehrere Feeds implementieren

Content Cards lassen sich in Ihrer App filtern, sodass nur bestimmte Karten angezeigt werden. So können Sie mehrere Content-Card-Feeds für unterschiedliche Anwendungsfälle betreiben, zum Beispiel einen Transaktions-Feed und einen Marketing-Feed. Dazu erstellen Sie im Braze-Dashboard verschiedene Kategorien von Content Cards, indem Sie Schlüssel-Wert-Paare festlegen. Anschließend erstellen Sie in Ihrer App oder auf Ihrer Website Feeds, die diese Arten von Content Cards unterschiedlich behandeln: Bestimmte Typen werden herausgefiltert, andere angezeigt.

Schritt 1: Schlüssel-Wert-Paare für Karten festlegen

Wenn Sie eine Content-Card-Kampagne erstellen, legen Sie für jede Karte Schlüssel-Wert-Paar-Daten fest. Mit diesem Schlüssel-Wert-Paar kategorisieren Sie die Karten. Schlüssel-Wert-Paare werden im Datenmodell der Karte in der Eigenschaft extras gespeichert.

In diesem Beispiel legen wir ein Schlüssel-Wert-Paar mit dem Schlüssel feed_type fest, das bestimmt, in welchem Content-Card-Feed die Karte angezeigt werden soll. Als Wert verwenden Sie den Namen Ihres jeweiligen angepassten Feeds, etwa home_screen oder marketing.

Schritt 2: Content Cards filtern

Sobald Sie die Schlüssel-Wert-Paare zugewiesen haben, erstellen Sie einen Feed mit einer Logik, die die gewünschten Karten anzeigt und Karten anderer Typen herausfiltert. In diesem Beispiel zeigen wir nur Karten mit dem passenden Schlüssel-Wert-Paar feed_type: "Transactional" an.

• 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];
  }
}