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 referenziert den Zeitraum, in dem das Braze SDK die Aktivitäten der Nutzer: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 der Inaktivität aktiv (es sei denn, Sie ändern den Standard-Timeout für die Sitzung oder der Nutzer:innen schließt die App.

Hinweis

Wenn Sie den Aktivitätslebenszyklus-Callback für Android eingerichtet haben, ruft Braze automatischopenSession() undcloseSession() 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 die Standard-Sitzungszeitüberschreitung). In diesem Fall wird eine neue Sitzung beginnen. Wenn der Nutzer:innen Ihre App schließt, während sie im Hintergrund läuft, werden die Daten der Sitzung möglicherweise erst dann an Braze gesendet, wenn er die App erneut öffnet.

Wenn Sie closeSession() aufrufen, wird die Sitzung nicht sofort beendet. Stattdessen wird die Sitzung nach 10 Sekunden beendet, wenn openSession() nicht erneut vom Nutzer:innen aufgerufen wird, der eine andere Aktivität startet.

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

Wenn Ihre App in den Hintergrund wechselt,UIApplicationDidEnterBackgroundNotificationwird getriggert. 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 Zeitlimit für die Sitzung (es sei denn, Sie ändern das Standard-Zeitlimit für die Sitzung). Wenn die seit Beginn der Sitzung verstrichene Zeit die Zeitüberschreitung überschreitet, wird eine neue Sitzung gestartet.

Aktualisieren des Feeds

Automatische Aktualisierung

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

• Eine neue Sitzung gestartet wird
• Der Standard-Content-Card-Feed geschlossen und nach mehr als 60 Sekunden seit der letzten Aktualisierung erneut geöffnet wird.

Tipp

Um aktuelle Content Cards dynamisch anzuzeigen, ohne sie manuell zu aktualisieren, wählen Sie bei der Kartenerstellung die Option At first impression aus. Diese Karten werden aktualisiert, sobald sie verfügbar sind.

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 Synchronisierung vs. teilweise Synchronisierung

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

• Vollständige Synchronisierung: Ruft alle Content Cards ab, für die ein:e Nutzer:in berechtigt ist. Vollständige Synchronisierungen erfolgen automatisch alle 7 Tage oder wenn changeUser() aufgerufen wird.
• Teilweise Synchronisierung: Ruft nur neue Content Cards seit der letzten Anfrage ab. Wenn der oder die Nutzer:in für keine neuen Karten berechtigt ist, 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 ausgelöst).

Teilweise Synchronisierungen reduzieren die Serverlast und den Akkuverbrauch des Geräts. Content Cards, die bereits empfangen wurden, 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-Limits

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

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

Wichtig

Das Braze SDK wendet außerdem Rate-Limits für Performance und Zuverlässigkeit an. Beachten Sie dies, wenn Sie automatisierte Tests durchführen oder manuelle Qualitätssicherung betreiben. Weitere Informationen finden Sie unter Braze SDK-Rate-Limits.

Anpassen der angezeigten Kartenreihenfolge

Sie können die Reihenfolge ändern, in der Ihre Content Cards angezeigt werden. So können Sie das Nutzererlebnis durch die Priorisierung bestimmter Inhalte, wie z. B. zeitkritischer Aktionen, feinabstimmen.

• web
• android
• swift

Passen Sie die Anzeigereihenfolge der Content Cards in Ihrem Feed an, indem Sie den Parameter filterFunction von showContentCards(): verwenden. 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 stützt sich auf einen IContentCardsUpdateHandler, um Sortierungen oder Änderungen von Content Cards zu verarbeiten, bevor sie im Feed angezeigt werden. Ein angepasster Update Handler kann über setContentCardUpdateHandler auf Ihrem ContentCardsFragment festgelegt werden.

Das Folgende ist der Standard-IContentCardsUpdateHandler und kann als Ausgangspunkt für Anpassungen verwendet werden:

Java-Beispiel anzeigen

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

Kotlin-Beispiel anzeigen

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 Card-Feeds an, indem Sie direkt die statische Variable Attributes.defaults ä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.

Anpassen der Nachricht „Leerer Feed“

Wenn sich ein:e Nutzer:in für keine Content Cards qualifiziert, zeigt das SDK die Fehlermeldung „Leerer Feed“ an: „We have no updates. Please check again later.“ Sie können diese Fehlermeldung wie folgt anpassen:

• web
• android
• swift

Das Internet-SDK unterstützt keine programmatische Ersetzung der Sprache für „Leerer Feed“. Sie können sie bei jeder Anzeige des Feeds ersetzen. Dies ist jedoch nicht empfehlenswert, da die Aktualisierung des Feeds einige Zeit in Anspruch nehmen kann und der leere Feed-Text nicht sofort angezeigt wird.

• android view system
• jetpack compose

Wenn das ContentCardsFragment feststellt, dass der oder die Nutzer:in für keine Content Cards in Frage kommt, zeigt es die Fehlermeldung „Leerer Feed“ an.

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

Den Stil, der zur Anzeige dieser Nachricht verwendet wird, finden Sie unter Braze.ContentCardsDisplay.Empty. Er wird 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 Content-Card-Stil-Elemente finden Sie unter Stil anpassen.

Um die Fehlermeldung „Leerer Feed“ mit Jetpack Compose anzupassen, können Sie einen emptyString an ContentCardsList übergeben. Sie können auch 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 ein Composable haben, das Sie stattdessen anzeigen möchten, können Sie emptyComposable an ContentCardsList übergeben. Wenn emptyComposable angegeben wird, 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 setzen.

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 die Sprache, die automatisch in leeren Content-Card-Feeds erscheint, indem Sie die lokalisierbaren Content-Card-Strings in der ContentCardsLocalizable.strings-Datei Ihrer App neu definieren.

Hinweis

Wenn Sie diese Nachricht in verschiedenen Lokalisierungssprachen aktualisieren möchten, suchen Sie die entsprechende Sprache in der Ordnerstruktur „Resources“ mit dem String ContentCardsLocalizable.strings.

Mehrere Feeds implementieren

Content Cards können in Ihrer App gefiltert werden, sodass nur bestimmte Karten angezeigt werden. So können Sie mehrere Content-Card-Feeds für verschiedene Anwendungsfälle einrichten. Sie können zum Beispiel sowohl einen Transaktions-Feed als auch einen Marketing-Feed pflegen. Erstellen Sie dazu verschiedene Kategorien von Content Cards, indem Sie Schlüssel-Wert-Paare im Braze-Dashboard festlegen. Erstellen Sie dann in Ihrer App oder auf Ihrer Website Feeds, die diese Arten von Content Cards unterschiedlich behandeln, indem Sie einige Typen herausfiltern und andere anzeigen.

1. Schritt: Schlüssel-Wert-Paare auf Karten setzen

Wenn Sie eine Content-Card-Kampagne erstellen, legen Sie Schlüssel-Wert-Paar-Daten auf jeder Karte fest. Sie verwenden dieses Schlüssel-Wert-Paar, um die Karten zu kategorisieren. Schlüssel-Wert-Paare werden in der Eigenschaft extras im Datenmodell der Karte gespeichert.

In diesem Beispiel legen wir ein Schlüssel-Wert-Paar mit dem Schlüssel feed_type fest, das angibt, in welchem Content-Card-Feed die Karte angezeigt werden soll. Der Wert entspricht dem Ihrer angepassten Feeds, z. B. home_screen oder marketing.

2. Schritt: 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 werden nur Karten mit einem passenden Schlüssel-Wert-Paar von feed_type: "Transactional" angezeigt.

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