Iterieren über kontextuelle Daten personalization-contexts

Erfahren Sie, wie Sie mithilfe der Handlebars-Iterationssyntax dynamische Listen mit Daten aus verschiedenen Quellen in Ihren Nachrichten anzeigen können, einschließlich Ereignissen, benutzerdefinierten Aktionsantworten und anderen kontextuellen Daten.

Überblick overview

Journey Optimizer bietet bei der Nachrichtenpersonalisierung Zugriff auf kontextuelle Daten aus mehreren Quellen. Sie können über Arrays aus diesen Quellen mithilfe der Handlebars-Syntax in nativen Kanälen (E-Mail, Push, SMS) iterieren, um dynamische Inhalte wie Produktlisten, Empfehlungen oder andere sich wiederholende Elemente anzuzeigen.

Verfügbare Kontextquellen:

In diesem Handbuch erfahren Sie, wie Sie über die Arrays aus den einzelnen Quellen in Ihren Nachrichten iterieren und wie Sie beim Konfigurieren von Journey-Aktivitäten mit Arrays arbeiten. Beginnen Sie mit Handlebars-Iterationssyntax, um die Grundlagen der Nachrichtenpersonalisierung zu verstehen, oder gehen Sie zu Arbeiten mit Arrays in Journey-Ausdrücken, um zu erfahren, wie Sie Array-Daten an benutzerdefinierte Aktionen und Datensatzsuchen übergeben.

Handlebars-Iterationssyntax syntax

Handlebars bietet die {{#each}} Helper zum Iterieren über Arrays. Die allgemeine Syntax lautet:

{{#each arrayPath as |item|}}
  <!-- Access item properties here -->
  {{item.property}}
{{/each}}

Wichtigste Punkte:

  • Ersetzen Sie arrayPath durch den Pfad zu Ihren Array-Daten
  • Ersetzen Sie item durch einen beliebigen Variablennamen (z. B. product, response, element)
  • Greifen Sie auf Eigenschaften jedes Elements über {{item.propertyName}} zu
  • Sie können mehrere {{#each}}-Blöcke für Arrays mit mehreren Ebenen verschachteln

Iterieren über Ereignisdaten event-data

Ereignisdaten sind verfügbar, wenn Ihre Journey durch ein Ereignis ausgelöst wird. Dies ist nützlich, um Daten anzuzeigen, die zum Zeitpunkt des Starts der Journey erfasst wurden, wie z. B. den Inhalt des Warenkorbs, bestellte Artikel oder Formularübermittlungen.

TIP
Sie können Ereignisdaten mit anderen Quellen kombinieren. Beispiele finden Sie unter Kombinieren mehrerer Kontextquellen.

Kontextpfad für Ereignisse

context.journey.events.<event_ID>.<fieldPath>
  • <event_ID>: Die eindeutige ID Ihres Ereignisses, wie in der Journey konfiguriert
  • <fieldPath>: Der Pfad zum Feld oder Array in Ihrem Ereignisschema

Beispiel: Warenkorbartikel aus einem Ereignis

Wenn Ihr Ereignisschema ein productListItems-Array enthält (Standard-XDM-Format), können Sie den Inhalt des Warenkorbs wie im folgenden Beispiel beschrieben anzeigen.

Beispiel-Code anzeigen
code language-handlebars
{{#each context.journey.events.event_ID.productListItems as |product|}}
  <div class="product">
    <h3>{{product.name}}</h3>
    <p>Quantity: {{product.quantity}}</p>
    <p>Price: ${{product.priceTotal}}</p>
  </div>
{{/each}}

Beispiel: Verschachtelte Arrays in Ereignissen

Verwenden Sie für verschachtelte Strukturen verschachtelte {{#each}}-Blöcke.

Beispiel-Code anzeigen
code language-handlebars
{{#each context.journey.events.event_ID.categories as |category|}}
  <h2>{{category.name}}</h2>
  <ul>
    {{#each category.items as |item|}}
      <li>{{item.title}}</li>
    {{/each}}
  </ul>
{{/each}}

Weitere Informationen zum Verschachteln finden Sie unter Best Practices.

Iterieren über Antworten auf benutzerdefinierte Aktionen custom-action-responses

Antworten auf benutzerdefinierte Aktionen umfassen Daten, die von externen API-Aufrufen zurückgegeben werden. Dies ist nützlich für die Anzeige von Echtzeitinformationen aus Ihren Systemen, z. B. Treuepunkte, Produktempfehlungen, Inventarstatus oder personalisierte Angebote.

NOTE
Benutzerdefinierte Aktionen müssen mit einer Antwort-Payload konfiguriert werden, damit diese Funktion verwendet werden kann. Weitere Informationen finden Sie in diesem Abschnitt. Sie können Antworten auf benutzerdefinierte Aktionen auch mit Ereignisdaten oder Datensatzsuchen kombinieren. Beispiele finden Sie unter Kombinieren mehrerer Kontextquellen.

Kontextpfad für benutzerdefinierte Aktionen

context.journey.actions.<actionName>.<fieldPath>
  • <actionName>: Der Name Ihrer benutzerdefinierten Aktion, wie in der Journey konfiguriert
  • <fieldPath>: Der Pfad zum Feld oder Array in der Antwort-Payload

Beispiel: Produktempfehlungen von einer API

Das folgende Beispiel zeigt, wie Sie über eine Reihe von Produktempfehlungen iterieren, die von einer benutzerdefinierten Aktion zurückgegeben wurden, und sie als individuelle Karten in Ihrer Nachricht anzeigen.

Beispiel-Code anzeigen

API-Antwort:

code language-json
{
  "recommendations": [
    {
      "productId": "12345",
      "productName": "Summer Jacket",
      "price": 89.99,
      "imageUrl": "https://example.com/jacket.jpg"
    },
    {
      "productId": "67890",
      "productName": "Running Shoes",
      "price": 129.99,
      "imageUrl": "https://example.com/shoes.jpg"
    }
  ]
}

Nachrichtenpersonalisierung:

code language-handlebars
<h2>Recommended for You</h2>
<div class="recommendations">
  {{#each context.journey.actions.GetRecommendations.recommendations as |item|}}
    <div class="product-card">
      <img src="{{item.imageUrl}}" alt="{{item.productName}}" />
      <h3>{{item.productName}}</h3>
      <p class="price">${{item.price}}</p>
    </div>
  {{/each}}
</div>

Beispiel: Verschachtelte Arrays aus benutzerdefinierten Aktionen

Das folgende Beispiel zeigt, wie Sie über eine Antwort auf benutzerdefinierte Aktionen iterieren, die verschachtelte Arrays enthält (ein Array von Objekten, wobei jedes Objekt ein anderes Array enthält). Dies zeigt die Verwendung verschachtelter {{#each}}-Schleifen für den Zugriff auf mehrere Datenebenen.

Beispiel-Code anzeigen

API-Antwort:

code language-json
{
  "id": "84632848268632",
  "responses": [
    { "productIDs": [1111, 2222, 3333] },
    { "productIDs": [4444, 5555, 6666] },
    { "productIDs": [7777, 8888, 9999] }
  ]
}

Nachrichtenpersonalisierung:

code language-handlebars
<h2>Product Groups</h2>
{{#each context.journey.actions.GetProducts.responses as |response|}}
  <div class="product-group">
    <ul>
      {{#each response.productIDs as |productID|}}
        <li>Product ID: {{productID}}</li>
      {{/each}}
    </ul>
  </div>
{{/each}}

Informationen zu komplexeren Verschachtelungsmustern finden Sie unter Best Practices.

Beispiel: Vorteile der Treuestufe

Das folgende Beispiel zeigt, wie Sie dynamische Vorteile basierend auf dem Treuestatus anzeigen.

Beispiel-Code anzeigen

API-Antwort:

code language-json
{
  "loyaltyTier": "gold",
  "benefits": [
    { "name": "Free shipping", "icon": "truck" },
    { "name": "20% discount", "icon": "percent" },
    { "name": "Priority support", "icon": "headset" }
  ]
}

Nachrichtenpersonalisierung:

code language-handlebars
<h2>Your {{context.journey.actions.GetLoyaltyInfo.loyaltyTier}} Member Benefits</h2>
<ul class="benefits">
  {{#each context.journey.actions.GetLoyaltyInfo.benefits as |benefit|}}
    <li>
      <span class="icon-{{benefit.icon}}"></span>
      {{benefit.name}}
    </li>
  {{/each}}
</ul>

Iterieren über die Ergebnisse der Datensatzsuche dataset-lookup

Die Aktivität Datensatzsuche ermöglicht das dynamische Abrufen von Daten aus Adobe Experience Platform-Datensätzen während der Journey-Laufzeit. Die angereicherten Daten werden als Array gespeichert und es kann in Ihren Nachrichten über sie iteriert werden.

AVAILABILITY
Die Aktivität „Datensatzsuche“ ist nur für eine begrenzte Anzahl von Organisationen verfügbar. Um Zugriff zu erhalten, wenden Sie sich an den Adobe-Support.

Weitere Informationen zum Konfigurieren der Aktivität „Datensatzsuche“ finden Sie in diesem Abschnitt. Die Datensatzsuche ist besonders leistungsstark in Kombination mit Ereignisdaten. Einen praktischen Anwendungsfall finden Sie unter Beispiel: Mit Datensatzsuche angereicherte Ereignisdaten.

Kontextpfad für Datensatzsuchen

context.journey.datasetLookup.<activityID>.entities
  • <activityID>: Die eindeutige ID Ihrer Aktivität „Datensatzsuche“
  • entities: Das Array der angereicherten Daten, die aus dem Datensatz abgerufen werden

Beispiel: Produktdetails aus einem Datensatz

Das folgende Beispiel zeigt, wie Sie eine Aktivität des Typs „Datensatzsuche“ verwenden, um Produktinformationen basierend auf SKUs abzurufen.

Beispiel-Code anzeigen

Konfiguration der Datensatzsuche:

  • Suchschlüssel: list(@event{purchase_event.products.sku})
  • Zurückzugebende Felder: ["SKU", "category", "price", "name"]

Nachrichtenpersonalisierung:

code language-handlebars
<h2>Product Details</h2>
<table>
  <thead>
    <tr>
      <th>Product Name</th>
      <th>Category</th>
      <th>Price</th>
    </tr>
  </thead>
  <tbody>
    {{#each context.journey.datasetLookup.3709000.entities as |product|}}
      <tr>
        <td>{{product.name}}</td>
        <td>{{product.category}}</td>
        <td>${{product.price}}</td>
      </tr>
    {{/each}}
  </tbody>
</table>

Beispiel: Gefilterte Iteration mit Datensatzdaten

Verwenden Sie bedingte {{#if}}-Anweisungen in Ihrer {{#each}}-Schleife, um die Ergebnisse der Datensatzsuche während der Iteration zu filtern und nur Elemente anzuzeigen, die bestimmten Kriterien entsprechen (z. B. Produkte aus einer bestimmten Kategorie). Siehe das Beispiel unten.

Beispiel-Code anzeigen
code language-handlebars
<h2>Household Products</h2>
{{#each context.journey.datasetLookup.3709000.entities as |product|}}
  {{#if product.category = "household"}}
    <div class="product">
      <h3>{{product.name}}</h3>
      <p>Price: ${{product.price}}</p>
    </div>
  {{/if}}
{{/each}}

Weitere Informationen zu bedingten Inhalten finden Sie unter Best Practices.

Beispiel: Berechnen der Gesamtsumme aus der Datensatzsuche

Das folgende Beispiel zeigt, wie Sie Gesamtsummen bei der Iteration über die Ergebnisse der Datensatzsuche berechnen und anzeigen.

Beispiel-Code anzeigen
code language-handlebars
{% let householdTotal = 0 %}
{{#each context.journey.datasetLookup.3709000.entities as |product|}}
  {%#if product.category = "household"%}
    {% let householdTotal = householdTotal + product.price %}
  {%/if%}
{{/each}}

<p>Your household products total: ${{householdTotal}}</p>

Verwenden technischer Journey-Eigenschaften technical-properties

Technische Journey-Eigenschaften ermöglichen den Zugriff auf Metadaten über die Journey-Ausführung, z. B. die Journey-ID und zusätzliche Kennungen. Diese können in Kombination mit Iterationsmustern nützlich sein, insbesondere zum Filtern von Arrays basierend auf bestimmten Journey-Instanzen.

Verfügbare technische Eigenschaften

context.journey.technicalProperties.journeyUID
context.journey.technicalProperties.supplementalId

Beispiel: Filtern von Array-Elementen mithilfe einer zusätzlichen Kennung

Bei Verwendung zusätzlicher IDs in ereignisgesteuerten Journeys mit Arrays können Sie so filtern, dass nur das für die aktuelle Journey-Instanz relevante Element angezeigt wird. Weitere Informationen zu zusätzlichen Kennungen finden Sie in diesem Handbuch.

Szenario: Eine Journey mit mehreren Buchungen wird ausgelöst, Sie möchten jedoch nur Informationen zu der spezifischen Buchung anzeigen (identifiziert durch eine zusätzliche ID), die diese Journey-Instanz ausgelöst hat.

Beispiel-Code anzeigen
code language-handlebars
{{#each context.journey.events.event_ID.bookingList as |booking|}}
  {%#if booking.bookingInfo.bookingNum = context.journey.technicalProperties.supplementalId%}
    <div class="booking-details">
      <h3>Your Booking: {{booking.bookingInfo.bookingNum}}</h3>
      <p>Destination: {{booking.bookingInfo.bookingCountry}}</p>
      <p>Date: {{booking.bookingInfo.bookingDate}}</p>
    </div>
  {%/if%}
{{/each}}

Beispiel: Einschließen der Journey-ID für Tracking

Das folgende Beispiel zeigt, wie Sie die Journey-ID zu Tracking-Zwecken in Ihre Nachricht aufnehmen.

Beispiel-Code anzeigen
code language-handlebars
<footer>
  <p>Journey Reference: {{context.journey.technicalProperties.journeyUID}}</p>
</footer>

Kombinieren mehrerer Kontextquellen combine-sources

Sie können Daten aus verschiedenen Quellen in derselben Nachricht kombinieren, um umfassende, personalisierte Erlebnisse zu erstellen. Dieser Abschnitt enthält praktische Beispiele für die kombinierte Verwendung mehrerer Kontextquellen.

Kontextquellen, die Sie kombinieren können:

Beispiel: Artikel im Warenkorb mit Echtzeit-Inventar

Das folgende Beispiel zeigt, wie Sie Ereignisdaten (Warenkorbinhalte) mit Daten benutzerdefinierter Aktionen (Inventarstatus) kombinieren.

Beispiel-Code anzeigen
code language-handlebars
<h2>Your Cart</h2>
{{#each context.journey.events.cartEvent.productListItems as |product|}}
  <div class="cart-item">
    <h3>{{product.name}}</h3>
    <p>Quantity: {{product.quantity}}</p>
    <p>Price: ${{product.priceTotal}}</p>
  </div>
{{/each}}

<h2>We Also Recommend</h2>
{{#each context.journey.actions.GetRecommendations.items as |recommendation|}}
  <div class="recommendation">
    <h4>{{recommendation.name}}</h4>
    <p>${{recommendation.price}}</p>
    {{#if recommendation.inStock}}
      <span class="badge">In Stock</span>
    {{else}}
      <span class="badge out-of-stock">Out of Stock</span>
    {{/if}}
  </div>
{{/each}}

Beispiel: Mit Datensatzsuche angereicherte Ereignisdaten

Das folgende Beispiel zeigt, wie Sie Ereignis-SKUs mit detaillierten Produktinformationen aus einer Datensatzsuche kombinieren.

Beispiel-Code anzeigen
code language-handlebars
<h2>Your Order Details</h2>
{{#each context.journey.events.orderEvent.productListItems as |item|}}
  <div class="order-item">
    <p><strong>SKU:</strong> {{item.SKU}}</p>
    <p><strong>Quantity:</strong> {{item.quantity}}</p>

    <!-- Enrich with dataset lookup data -->
    {{#each context.journey.datasetLookup.1234567.entities as |enrichedProduct|}}
      {{#if enrichedProduct.SKU = item.SKU}}
        <p><strong>Product Name:</strong> {{enrichedProduct.name}}</p>
        <p><strong>Category:</strong> {{enrichedProduct.category}}</p>
        <img src="{{enrichedProduct.imageUrl}}" alt="{{enrichedProduct.name}}" />
      {{/if}}
    {{/each}}
  </div>
{{/each}}

Beispiel: Kombinieren mehrerer Quellen mit technischen Eigenschaften

Das folgende Beispiel zeigt, wie Sie mehrere Kontextquellen (Profildaten, Ereignisdaten, benutzerdefinierte Aktionen und technische Eigenschaften) in einer einzigen Nachricht kombinieren.

Beispiel-Code anzeigen
code language-handlebars
<div class="personalized-content">
  <!-- Profile data -->
  <h1>Hello {{profile.person.name.firstName}},</h1>

  <!-- Event data iteration -->
  <h2>Your Recent Purchases</h2>
  {{#each context.journey.events.purchaseEvent.items as |purchase|}}
    <div class="purchase">
      <p>{{purchase.productName}} - ${{purchase.price}}</p>
    </div>
  {{/each}}

  <!-- Custom action response iteration -->
  <h2>Recommended for You</h2>
  {{#each context.journey.actions.GetPersonalizedRecs.recommendations as |rec|}}
    <div class="recommendation">
      <h3>{{rec.title}}</h3>
      <p>{{rec.description}}</p>
    </div>
  {{/each}}

  <!-- Technical properties -->
  <footer>
    <p class="fine-print">Journey ID: {{context.journey.technicalProperties.journeyUID}}</p>
  </footer>
</div>

Andere Kontexttypen other-contexts

Dieses Handbuch konzentriert sich auf die Iteration über Arrays. Es stehen jedoch andere Kontexttypen für die Personalisierung zur Verfügung, die in der Regel keine Iteration erfordern. Auf diese wird direkt zugegriffen, anstatt sie in Schleifen zu durchlaufen:

  • Profilattribute (profile.*): Einzelne Profilfelder aus Adobe Experience Platform
  • Zielgruppen (inAudience()): Prüfungen der Zielgruppenzugehörigkeit
  • Angebotsentscheidungen: Entscheidungs-Management-Angebote
  • Zielattribute (nur orchestrierte Kampagnen): Auf der Kampagnen-Arbeitsfläche berechnete Attribute
  • Token (context.token): Sitzungs- oder Authentifizierungs-Token

Die vollständige Personalisierungssyntax und Beispiele, die diese Quellen verwenden, finden Sie unter:

Arbeiten mit Arrays in Journey-Ausdrücken arrays-in-journeys

Die vorherigen Abschnitte fokussierten sich auf die Iteration über Arrays bei der Nachrichtenpersonalisierung mithilfe von Handlebars. Sie können jedoch auch beim Konfigurieren von Journey-Aktivitäten mit Arrays arbeiten. In diesem Abschnitt wird erläutert, wie Sie Array-Daten aus Ereignissen in Journey-Ausdrücken verwenden, insbesondere wenn Sie Daten an benutzerdefinierte Aktionen übergeben oder Arrays mit Datensatzsuchen verwenden.

IMPORTANT
Journey-Ausdrücke verwenden eine andere Syntax als die Handlebars-Personalisierung. In der Journey-Konfiguration (z. B. mit Parametern oder Bedingungen benutzerdefinierter Aktionen) verwenden Sie den Journey-Ausdruckseditor mit Funktionen wie first, all und serializeList. Im Nachrichteninhalt verwenden Sie die Handlebars-Syntax mit {{#each}}-Schleifen.

Übergeben von Array-Werten an Parameter benutzerdefinierter Aktionen arrays-to-custom-actions

Beim Konfigurieren benutzerdefinierter Aktionen müssen Sie häufig Werte aus Ereignis-Arrays extrahieren und als Parameter übergeben. In diesem Abschnitt werden gängige Muster behandelt.

Weitere Informationen zum Übergeben von Sammlungen finden Sie unter Übergeben von Sammlungen in Parametern benutzerdefinierter Aktionen.

Extrahieren eines einzelnen Werts aus einem Array

Anwendungsfall: Abrufen eines bestimmten Felds aus einem Ereignis-Array, das als Abfrageparameter in einer GET-Anfrage übergeben wird.

Beispiel-Code anzeigen

Beispielszenario: Extrahieren der ersten SKU mit einem Preis größer als 0 aus einer Produktliste.

Beispiel für ein Ereignisschema:

code language-json
{
  "commerce": {
    "productListItems": [
      { "SKU": "SKU-1", "priceTotal": 10.0 },
      { "SKU": "SKU-2", "priceTotal": 0.0 },
      { "SKU": "SKU-3", "priceTotal": 20.0 }
    ]
  }
}

Konfiguration benutzerdefinierter Aktionen:

  1. Konfigurieren Sie in Ihrer benutzerdefinierten Aktion einen Abfrageparameter (z. B. sku) vom Typ string
  2. Markieren Sie ihn als Variable, um dynamische Werte zuzulassen

Journey-Ausdruck im Aktionsparameter:

code language-javascript
@event{YourEventName.commerce.productListItems.first(currentEventField.priceTotal > 0).SKU}

Erklärung:

  • @event{YourEventName}: Verweist auf Ihr Journey-Ereignis
  • .first(currentEventField.condition): Gibt das erste Array-Element zurück, das der Bedingung entspricht
  • currentEventField: Stellt jedes Element im Ereignis-Array dar, während Sie es durchlaufen
  • .SKU: Extrahiert das SKU-Feld aus dem zugeordneten Element
  • Ergebnis: "SKU-1" (eine für den Aktionsparameter geeignete Zeichenfolge)

Weitere Informationen über die first-Funktion finden Sie unter Funktionen zur Sammlungsverwaltung.

Erstellen einer Werteliste aus einem Array

Anwendungsfall: Erstellen einer kommagetrennten Liste von IDs, die als Abfrageparameter übergeben werden (z. B. /products?ids=sku1,sku2,sku3).

Beispiel-Code anzeigen

Konfiguration benutzerdefinierter Aktionen:

  1. Konfigurieren Sie einen Abfrageparameter (z. B. ids) vom Typ string
  2. Markieren Sie ihn als Variable

Journey-Ausdruck:

code language-javascript
serializeList(
  @event{YourEventName.commerce.productListItems.all(currentEventField.priceTotal > 0).SKU},
  ",",
  true
)

Erklärung:

  • .all(currentEventField.condition): Gibt alle Array-Elemente zurück, die der Bedingung entsprechen (gibt eine Liste zurück)

  • currentEventField: Stellt jedes Element im Ereignis-Array dar, während Sie es durchlaufen

  • .SKU: Stellt die Liste so dar, dass nur SKU-Werte enthalten sind

  • serializeList(list, delimiter, addQuotes): Fügt die Liste zu einer Zeichenfolge zusammen

    • ",": Verwendet Komma als Trennzeichen
    • true: Schließt jedes Zeichenfolgenelement in Anführungszeichen ein
  • Ergebnis: "SKU-1,SKU-3" (für einen Abfrageparameter geeignet)

Weitere Informationen:

Die Verarbeitung von Sammlungen für benutzerdefinierte Aktionen wird unter Übergeben von Sammlungen an Parameter benutzerdefinierter Aktionen beschrieben.

Übergeben eines Arrays von Objekten an eine benutzerdefinierte Aktion

Anwendungsfall: Senden eines vollständigen Arrays von Objekten in einem Anfrageinhalt (für POST oder GET mit Text).

Beispiel-Code anzeigen

Beispiel für einen Anfragetext:

code language-json
{
  "ctxt": {
    "products": [
      {
        "id": "productA",
        "name": "Product A",
        "price": 20.1,
        "color": "blue"
      }
    ]
  }
}

Konfiguration benutzerdefinierter Aktionen:

  1. Definieren Sie products im Anfragetext als Typ listObject
  2. Markieren Sie dies als Variable
  3. Definieren Sie die Objektfelder: id, name, price, color (für jedes ist dann eine Zuordnung möglich)

Konfiguration der Journey-Arbeitsfläche:

  1. Legen Sie im erweiterten Modus den Sammlungsausdruck fest:

    code language-javascript
    @event{YourEventName.commerce.productListItems.all(currentEventField.priceTotal > 0)}
    
  2. In der Benutzeroberfläche für die Sammlungszuordnung:

    • Erstellen Sie die Zuordnung idproductListItems.SKU
    • Erstellen Sie die Zuordnung nameproductListItems.name
    • Erstellen Sie die Zuordnung priceproductListItems.priceTotal
    • Erstellen Sie die Zuordnung colorproductListItems.color

Journey Optimizer erstellt das Array von Objekten, die Ihrer Aktions-Payload-Struktur entsprechen.

note note
NOTE
Verwenden Sie currentEventField beim Arbeiten mit Ereignis-Arrays, um auf jedes Element zu verweisen. Verwenden Sie currentDataPackField für Datenquellensammlungen (Adobe Experience Platform). Verwenden Sie currentActionField für Sammlungen von Antworten auf benutzerdefinierte Aktionen.

Weitere Informationen finden Sie unter Übergeben von Sammlungen an Parameter benutzerdefinierter Aktionen.

Verwenden von Arrays mit Datensatzsuchen arrays-with-dataset-lookup

Bei Verwendung der Aktivität Datensatzsuche können Sie ein Array von Werten als Suchschlüssel übergeben, um angereicherte Daten abzurufen.

Beispiel: Nachschlagen der Produktdetails für alle SKUs in einem Ereignis-Array.

Beispiel-Code anzeigen

Konfiguration der Datensatzsuche:

Verwenden Sie list() im Feld „Suchschlüssel“, um einen Array-Pfad in eine Liste zu konvertieren:

code language-javascript
list(@event{purchaseEvent.productListItems.SKU})

Dadurch wird eine Liste aller SKU-Werte erstellt, die im Datensatz nachgeschlagen werden sollen. Die Ergebnisse sind als Array unter context.journey.datasetLookup.<activityID>.entities verfügbar, über das Sie in Ihrer Nachricht iterieren können (siehe Iterieren über die Ergebnisse der Datensatzsuche).

Einschränkungen und Muster array-limitations

Beachten Sie diese Einschränkungen beim Arbeiten mit Arrays in Journeys:

Keine dynamische Schleife über Arrays im Journey Flow

Journeys können keine dynamischen Schleifen erstellen, bei denen ein Aktionsknoten für jedes Element in einem Array mehrmals ausgeführt wird. Dadurch sollen Ausreißer von Leistungsproblemen verhindert werden.

Folgendes ist nicht möglich:

  • Dynamisches Ausführen einer benutzerdefinierten Aktion einmal pro Array-Element
  • Erstellen mehrerer Journey-Verzweigungen basierend auf der Array-Länge

Stattdessen empfohlene Muster:

  1. Senden Sie alle Elemente gleichzeitig: Übergeben Sie das gesamte Array oder eine serialisierte Liste an eine einzelne benutzerdefinierte Aktion, die alle Elemente verarbeitet. Siehe Erstellen einer Werteliste aus einem Array.

  2. Verwenden Sie externe Aggregation: Lassen Sie Ihre externe API mehrere IDs akzeptieren und kombinierte Ergebnisse in einem einzigen Aufruf zurückgeben.

  3. Führen Sie eine Vorberechnung in AEP durch: Verwenden Sie berechnete Attribute, um Werte aus Arrays auf Profilebene vorab zu berechnen.

  4. Extrahieren Sie Einzelwerte: Wenn Sie nur einen Wert benötigen, extrahieren Sie ihn mithilfe von first oder head. Siehe Extrahieren eines einzelnen Werts aus einem Array.

Weitere Informationen finden Sie unter Leitlinien und Einschränkungen.

Überlegungen zur Array-Größe

Große Arrays können die Journey-Leistung beeinträchtigen:

  • Ereignis-Arrays: Halten Sie Ereignis-Payloads unter insgesamt 50 KB
  • Antworten auf benutzerdefinierte Aktionen:: Halten Sie Antwort-Payloads unter 100 KB
  • Ergebnisse der Datensatzsuche: Begrenzen Sie die Anzahl der Suchschlüssel und zurückgegebenen Entitäten

Vollständiges Beispiel: Ereignis-Array für benutzerdefinierte Aktion complete-example

Im Folgenden finden Sie einen vollständigen Workflow, der zeigt, wie ein Ereignis-Array mit einer benutzerdefinierten Aktion verwendet wird.

Szenario: Wenn eine Person ihren Warenkorb abbricht, senden Sie Warenkorbdaten an eine externe Empfehlungs-API, um personalisierte Vorschläge zu erhalten, und zeigen Sie diese dann in einer E-Mail an.

Beispiel-Code anzeigen

Schritt 1: Konfigurieren der benutzerdefinierten Aktion

Erstellen Sie eine benutzerdefinierte Aktion „GetCartRecommendations“:

  • Methode: POST
  • URL: https://api.example.com/recommendations
  • Anfrageinhalt:
code language-json
{
  "cartItems": [
    {
      "sku": "string",
      "price": 0,
      "quantity": 0
    }
  ]
}
  • Markieren Sie cartItems als Typ listObject und Variable
  • Definieren Sie Felder: sku (Zeichenfolge), price (Zahl), quantity (Ganzzahl)

Weitere Informationen finden Sie unter Konfigurieren einer benutzerdefinierten Aktion.

Schritt 2: Konfigurieren der Antwort-Payload

Konfigurieren Sie die Antwort in der benutzerdefinierten Aktion:

code language-json
{
  "recommendations": [
    {
      "productId": "string",
      "productName": "string",
      "price": 0,
      "imageUrl": "string"
    }
  ]
}

Weitere Informationen finden Sie unter Verwenden von Antworten auf API-Aufrufe.

Schritt 3: Verknüpfen der Aktion in der Journey

  1. Fügen Sie nach dem Ereignis des Warenkorbabbruchs die benutzerdefinierte Aktion hinzu

  2. Im erweiterten Modus für die cartItems-Sammlung:

    code language-javascript
    @event{cartAbandonment.commerce.productListItems.all(currentEventField.quantity > 0)}
    
  3. Ordnen Sie die Sammlungsfelder zu:

    • skuproductListItems.SKU
    • priceproductListItems.priceTotal
    • quantityproductListItems.quantity

Schritt 4: Verwenden der Antwort in Ihrer E-Mail

Iterieren Sie in Ihrem E-Mail-Inhalt über die Empfehlungen:

code language-handlebars
<h2>We noticed you left these items in your cart</h2>
{{#each context.journey.events.cartAbandonment.productListItems as |item|}}
  <div class="cart-item">
    <p>{{item.name}} - Quantity: {{item.quantity}}</p>
  </div>
{{/each}}

<h2>You might also like</h2>
{{#each context.journey.actions.GetCartRecommendations.recommendations as |rec|}}
  <div class="recommendation">
    <img src="{{rec.imageUrl}}" alt="{{rec.productName}}" />
    <h3>{{rec.productName}}</h3>
    <p>${{rec.price}}</p>
  </div>
{{/each}}

Schritt 5: Testen der Konfiguration

Bevor Sie eine Live-Journey ausführen, testen Sie die benutzerdefinierte Aktion mit der Funktion „Testanfrage senden“ in der Aktionskonfiguration, um die erstellte Anfrage und die Werte zu überprüfen.

  1. Verwenden Sie den Journey-Testmodus
  2. Lösen Sie mit Beispielereignisdaten aus, einschließlich eines productListItems Arrays
  3. Prüfen Sie, ob die benutzerdefinierte Aktion die richtige Array-Struktur erhält
  4. Prüfen Sie die Aktionstestprotokolle
  5. Zeigen Sie eine Vorschau der E-Mail an, um zu bestätigen, dass beide Arrays korrekt angezeigt werden

Weitere Informationen finden Sie unter Fehlerbehebung bei benutzerdefinierten Aktionen.

Best Practices best-practices

Befolgen Sie diese Best Practices bei der Iteration über kontextuelle Daten, um eine verwaltbare, leistungsstarke Personalisierung zu erstellen.

Verwenden aussagekräftiger Variablennamen

Wählen Sie Variablennamen, die klar angeben, worüber die Iteration erfolgt. Dadurch wird der Code besser lesbar und leichter zu verwalten. Weitere Informationen zur Personalisierungssyntax:

Beispiel-Code anzeigen
code language-handlebars
<!-- Good -->
{{#each products as |product|}}
{{#each users as |user|}}
{{#each recommendations as |recommendation|}}

<!-- Less clear -->
{{#each items as |item|}}
{{#each array as |element|}}

Ausdrucksfragmente in Schleifen

Wenn Sie Ausdrucksfragmente in {{#each}}-Schleifen verwenden, beachten Sie, dass Sie keine Variablen mit Schleifenbereich als Fragmentparameter übergeben können. Fragmente können jedoch auf globale Variablen zugreifen, die im Nachrichteninhalt außerhalb des Fragments definiert sind.

Beispiel-Code anzeigen

Unterstütztes Muster – Verwenden globaler Variablen:

code language-handlebars
{% let globalDiscount = 15 %}

{{#each context.journey.actions.GetProducts.items as |product|}}
  <div class="product">
    <h3>{{product.name}}</h3>
    {{fragment id='ajo:fragment123/variant456' mode='inline'}}
  </div>
{{/each}}

Das Fragment kann auf globalDiscount verweisen, da es global in der Nachricht definiert ist.

Nicht unterstützt – Übergeben von Schleifenvariablen:

code language-handlebars
{{#each products as |product|}}
  <!-- This will NOT work as expected -->
  {{fragment id='ajo:fragment123/variant456' currentProduct=product}}
{{/each}}

Problemumgehung: Fügen Sie die Personalisierungslogik direkt in Ihre Schleife ein, anstatt ein Fragment zu verwenden, oder rufen Sie das Fragment außerhalb der Schleife auf.

Erfahren Sie mehr über die Verwendung von Ausdrucksfragmenten in Schleifen, einschließlich detaillierter Beispiele und zusätzlicher Problemumgehungen.

Verarbeiten leerer Arrays

Verwenden Sie die {{else}}-Klausel, um Fallback-Inhalte bereitzustellen, wenn ein Array leer ist. Weitere Informationen zu Helper-Funktionen:

Beispiel-Code anzeigen
code language-handlebars
{{#each context.journey.actions.GetRecommendations.items as |item|}}
  <div>{{item.name}}</div>
{{else}}
  <p>No recommendations available at this time.</p>
{{/each}}

Kombinieren mit bedingten Helpern

Verwenden Sie {{#if}} in Schleifen für bedingte Inhalte. Weitere Informationen zu bedingten Regeln und Beispiele finden Sie in den Abschnitten Antworten auf benutzerdefinierte Aktionen und Datensatzsuche.

Beispiel-Code anzeigen
code language-handlebars
{{#each context.journey.actions.GetProducts.items as |product|}}
  <div class="product">
    <h3>{{product.name}}</h3>
    {{#if product.onSale}}
      <span class="badge">On Sale!</span>
    {{/if}}
    {{#if product.newArrival}}
      <span class="badge">New</span>
    {{/if}}
  </div>
{{/each}}

Begrenzen der Iteration für gute Leistung

Bei großen Arrays sollten Sie die Anzahl der Iterationen begrenzen:

Beispiel-Code anzeigen
code language-handlebars
<!-- Display only first 5 items -->
{{#each context.journey.actions.GetProducts.items as |product|}}
  {{#if @index < 5}}
    <div>{{product.name}}</div>
  {{/if}}
{{/each}}

Zugreifen auf Array-Metadaten

Handlebars bieten spezielle Variablen in Schleifen, die bei erweiterten Iterationsmustern helfen:

  • @index: Aktueller Iterationsindex (0-basiert)
  • @first: „Wahr“ für die erste Iteration
  • @last: „Wahr“ für die letzte Iteration
Beispiel-Code anzeigen
code language-handlebars
{{#each products as |product|}}
  <div class="product {{#if @first}}featured{{/if}}">
    {{@index}}. {{product.name}}
  </div>
{{/each}}
NOTE
Diese Handlebars-Variablen (@index, @first, @last) sind nur in {{#each}}-Schleifen bei der Nachrichtenpersonalisierung verfügbar. Verwenden Sie zum Arbeiten mit Arrays in Journey-Ausdrücken (z. B. Abrufen des ersten Elements aus einem Array vor der Übergabe an eine benutzerdefinierte Aktion) Array-Funktionen wie head, first oder all. Weitere Informationen finden Sie unter Arbeiten mit Arrays in Journey-Ausdrücken.

Fehlerbehebung troubleshooting

Haben Sie Probleme mit der Iteration? In diesem Abschnitt werden gängige Probleme und Lösungen behandelt.

Array wird nicht angezeigt

Problem: Ihre Array-Iteration zeigt keine Inhalte an.

Mögliche Ursachen und Lösungen anzeigen

Mögliche Ursachen und Lösungen:

  1. Falscher Pfad: Prüfen Sie den genauen Pfad zu Ihrem Array basierend auf der Kontextquelle:

  2. Array ist leer: Fügen Sie eine {{else}}-Klausel hinzu, um zu prüfen, ob das Array keine Daten enthält. Beispiele finden Sie unter Best Practices.

  3. Daten noch nicht verfügbar: Stellen Sie sicher, dass die benutzerdefinierte Aktion, das Ereignis oder die Aktivität „Datensatzsuche“ vor der Nachrichtenaktivität in Ihrem Journey Flow ausgeführt wurde.

Syntaxfehler

Problem: Die Ausdrucksvalidierung schlägt fehl oder die Nachricht wird nicht gerendert.

Häufige Fehler anzeigen

Häufige Fehler:

  • Fehlende schließende Tags: Jedes {{#each}} muss über ein {{/each}} verfügen. Prüfen Sie die Handlebars-Iterationssyntax auf die korrekte Struktur.
  • Falscher Variablenname: Stellen Sie sicher, dass der Variablenname im gesamten Block konsistent verwendet wird. Siehe Best Practices für Namenskonventionen.
  • Falsche Pfadtrennzeichen: Verwenden Sie Punkte (.) anstelle von Schrägstrichen oder anderen Zeichen.

Ausdrucksfragmente funktionieren nicht in Schleifen

Problem: Ein Ausdrucksfragment zeigt nicht den erwarteten Inhalt an, wenn es in einer {{#each}}-Schleife verwendet wird, oder es zeigt eine leere/unerwartete Ausgabe an.

Mögliche Ursachen und Lösungen anzeigen

Mögliche Ursachen und Lösungen:

  1. Versuch, Schleifenvariablen als Parameter zu übergeben: Ausdrucksfragmente können keine Variablen mit Schleifenumfang (wie das aktuelle Iterationselement) als Parameter empfangen. Dies ist eine bekannte Einschränkung.

    Lösung: Verwenden Sie eine der folgenden Problemumgehungen:

    • Definieren Sie globale Variablen in Ihrer Nachricht, auf die das Fragment zugreifen kann
    • Schließen Sie Personalisierungslogik direkt in die Schleife ein, anstatt ein Fragment zu verwenden
    • Rufen Sie das Fragment außerhalb der Schleife auf, wenn es keine schleifenspezifischen Daten benötigt
  2. Fragment erwartet einen Parameter, der nicht verfügbar ist: Wenn Ihr Fragment für den Empfang bestimmter Eingabeparameter konzipiert wurde, funktioniert es nicht ordnungsgemäß, wenn diese Parameter nicht aus einer Schleife heraus übergeben werden können.

    Lösung: Strukturieren Sie Ihren Ansatz so um, dass globale Variablen verwendet werden, auf die das Fragment zugreifen kann. Beispiele finden Sie unter Best Practices – Ausdrucksfragmente in Schleifen.

  3. Falscher Variablenbereich: Das Fragment versucht möglicherweise, auf eine Variable zu verweisen, die nur innerhalb des Schleifenbereichs vorhanden ist.

    Lösung: Definieren Sie alle Variablen, die das Fragment benötigt, auf Nachrichtenebene (außerhalb der Schleife), damit sie global zugänglich sind.

Erfahren Sie mehr über die Verwendung von Ausdrucksfragmenten in Schleifen, einschließlich detaillierter Erläuterungen, Beispiele und empfohlener Muster.

Testen der Iterationen

Verwenden Sie den Journey-Testmodus, um Ihre Iterationen zu prüfen. Dies ist besonders wichtig bei der Verwendung von benutzerdefinierten Aktionen oder Datensatzsuchen:

Testschritte anzeigen
  1. Starten Sie die Journey im Testmodus
  2. Lösen Sie das Ereignis oder die benutzerdefinierte Aktion mit Beispieldaten aus
  3. Prüfen Sie die Nachrichtenvorschau, um sicherzustellen, dass die Iteration korrekt angezeigt wird
  4. Prüfen Sie die Testmodusprotokolle auf Fehler (siehe Testmodusprotokolle für benutzerdefinierte Aktionen)

Personalisierungsgrundlagen: Erste Schritte mit der Personalisierung | Hinzufügen von Personalisierung | Personalisierungssyntax | Helper-Funktionen | Erstellen von bedingten Regeln

Journey-Konfiguration: Über Ereignisse | Konfigurieren benutzerdefinierter Aktionen | Übergeben von Sammlungen in Parameter benutzerdefinierter Aktionen | Verwenden von API-Aufrufantworten in benutzerdefinierten Aktionen | Fehlerbehebung bei benutzerdefinierten Aktionen | Verwenden von Adobe Experience Platform-Daten in Journeys | Verwenden zusätzlicher Kennungen in Journeys | Leitlinien und Einschränkungen | Testen der Journey

Journey-Ausdrucksfunktionen: Erweiterter Ausdruckseditor | Funktionen zur Sammlungsverwaltung (first, all, last) | Listenfunktionen (serializeList, filter, sort) | Array-Funktionen (head, tail)

Personalisierungs-Anwendungsfälle: E-Mail zu Warenkorbabbruch | Benachrichtigung zum Bestellstatus

Nachrichten-Design: Erste Schritte beim E-Mail-Design | Erstellen von Push-Benachrichtigungen | Erstellen von SMS-Nachrichten | Vorschau und Testen von Inhalten

recommendation-more-help
b22c9c5d-9208-48f4-b874-1cefb8df4d76