Stayfilm

Stayfilm ist eine REST API für die automatisierte, personalisierte Videoproduktion in großem Umfang. Die Plattform integriert Daten, Bilder, Text, Soundtracks, Narration und visuelle Effekte, um angepasste Videoinhalte für E-Commerce, Marktplätze, CRM-Workflows und Marketing-Campaigns zu generieren.

Diese Integration sendet Render-Jobs von Braze an die Stayfilm-API, empfängt Callbacks, wenn Videos bereit sind, und speichert Video-URLs und Status in Nutzerprofilen zur Verwendung in Campaigns und Canvases.

Diese Integration wird von Stayfilm gepflegt.

Anwendungsfälle

Stayfilm unterstützt die personalisierte Videozustellung über den gesamten Kundenlebenszyklus, einschließlich:

• Onboarding- und Willkommens-Journeys: Begrüßen Sie neue Nutzer:innen mit Videos, die auf ihr Profil oder ihren Anmeldekontext personalisiert sind
• Produkt- und Marktplatzinhalte: Generieren Sie produktbezogene Videos aus Katalog- oder nutzerbereitgestellten Medien
• Conversion und Aktivierung: Verstärken Sie wichtige Aktionen mit kontextuellem Video-Messaging
• Kundenbindung und Upselling: Heben Sie personalisierte Angebote oder Nutzungsmeilensteine im Videoformat hervor
• Rückgewinnung und Churn-Prävention: Reaktivieren Sie inaktive Nutzer:innen mit maßgeschneiderten Videoinhalten

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie über Folgendes verfügen:

Funktionsweise der Integration

Diese Integration verwendet einen bidirektionalen Webhook-Ablauf:

1. Ausgehend: Eine Braze-Webhook-Campaign sendet einen Render-Job an den Stayfilm-Endpunkt POST /Job. Die Anfrage enthält Nutzermedien, Template-Konfiguration und CallbackRelayData, das auf die external_id der Braze-Nutzer:innen gesetzt ist.
2. Eingehend: Wenn Stayfilm das Rendering abgeschlossen hat, sendet es einen Callback an Ihre Braze-Datentransformations-Webhook-URL. Die Transformation ordnet die Antwort angepassten Attributen und angepassten Events im entsprechenden Nutzerprofil zu.
3. Zustellung: Verwenden Sie das gespeicherte Attribut stayfilm_video_url in Messaging-Kanälen, z. B. in einer In-App-Nachricht mit angepasstem HTML.

Die Datentransformation in dieser Anleitung schreibt die folgenden angepassten Attribute:

Die Transformation zeichnet außerdem angepasste Events mit den Namen stayfilm_video_ready oder stayfilm_video_failed auf.

Integration

Die folgenden Schritte führen Sie durch einen Proof of Concept. Nachdem Sie den Ablauf validiert haben, passen Sie den Job-Payload, die Attribute und das Messaging an Ihren Anwendungsfall an.

Schritt 1: Testnutzer:in erstellen

Erstellen Sie ein Testnutzerprofil, das Sie beim Aufbau und der Validierung der Integration verwenden. Weitere Informationen finden Sie unter Nutzer:innen importieren.

1. Gehen Sie zu Audience > Import Users.
2. Wählen Sie Quick User Add aus.
3. Geben Sie eine external_id und alle weiteren erforderlichen Felder ein und wählen Sie dann Create new user aus.

Wichtig

Verwenden Sie keine personenbezogenen Daten – wie E-Mail, Telefonnummer, vollständigen Namen, Ausweisnummer, Adresse oder Bestelldetails – als external_id. Behandeln Sie external_id in dieser gesamten Integration als case-sensitive.

Diese Anleitung verwendet stayfilm-poc-001 als Beispiel-external_id. Notieren Sie sich den gewählten Wert, da Sie ihn in späteren Schritten benötigen.

Schritt 2: Datentransformation erstellen

Erstellen Sie eine Datentransformation, um Stayfilm-Callbacks zu empfangen und Nutzerprofile zu aktualisieren.

1. Gehen Sie zu Data Settings > Data Transformation.
2. Wählen Sie Create transformation aus.
3. Geben Sie einen Namen ein, z. B. Stayfilm Callback Data Transformation.
4. Wählen Sie unter Editing experience die Option Start from scratch aus.
5. Wählen Sie unter Select destination > Destination die Option POST: Track users aus.
6. Wählen Sie Create transformation aus.
7. Ersetzen Sie den Standard-Transformationscode durch Folgendes:

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
const brazeExternalId = payload.RelayedData;
if (!brazeExternalId) {
  throw new Error("Missing RelayedData. Expected Stayfilm callback to relay the Braze external_id from CallbackRelayData.");
}

const idJob = payload.IdJob || null;
const producedFiles = payload.ProducedFiles || {};
const videoUrl = producedFiles?.Videos?.VideoMP4?.Url || null;
const errorMessage = payload.ErrorMessage || null;
const hasError = payload.HasError === true || Boolean(errorMessage);
const isReady = !hasError && Boolean(videoUrl);
const now = new Date().toISOString();

let brazecall = {
  attributes: [
    {
      external_id: brazeExternalId,
      _update_existing_only: true,
      stayfilm_video_status: isReady ? "ready" : "failed",
      stayfilm_video_url: videoUrl || null,
      stayfilm_job_id: idJob,
      stayfilm_render_error: errorMessage,
      stayfilm_callback_received_at: now
    }
  ],
  events: [
    {
      external_id: brazeExternalId,
      _update_existing_only: true,
      name: isReady ? "stayfilm_video_ready" : "stayfilm_video_failed",
      time: now,
      properties: {
        stayfilm_job_id: idJob,
        stayfilm_video_url: videoUrl || null,
        stayfilm_render_error: errorMessage,
        stayfilm_status: payload.Status || payload.status || null
      }
    }
  ]
};

return brazecall;

8. Wählen Sie Save aus und kopieren Sie dann die generierte Webhook-URL.
9. Senden Sie eine Test-POST-Anfrage an die Webhook-URL mit dem folgenden Beispiel-Stayfilm-Callback-JSON. Setzen Sie RelayedData auf die external_id der Testnutzer:in, die Sie in Schritt 1 erstellt haben.

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "IdJob": "debug-job-001",
  "HasError": false,
  "Status": "DRAFT_DONE",
  "ProducedFiles": {
    "Videos": {
      "VideoMP4": {
        "Url": "https://example.com/stayfilm-poc-video.mp4"
      }
    }
  },
  "RelayedData": "stayfilm-poc-001"
}

Senden Sie die Anfrage mit cURL, Postman oder einem ähnlichen Tool. Eine erfolgreiche Antwort gibt den HTTP-Status 201 mit {"message": "success"} zurück.

10. Gehen Sie zu Data Settings > Data Transformation und laden Sie die Seite neu, wenn Ihre Transformation nicht in der Liste erscheint.
11. Öffnen Sie die Transformation und wählen Sie Validate aus. Bestätigen Sie, dass die Validierung unter Output erfolgreich ist.
12. Wählen Sie Activate aus.
13. Stellen Sie Stayfilm die kopierte Webhook-URL als Ihre Callback-URL bereit.

Hinweis

Wenn Sie mehr als die Braze-external_id in CallbackRelayData speichern, aktualisieren Sie den Transformationscode, um RelayedData entsprechend zu parsen.

Schritt 3: Webhook-Campaign zum Senden von Jobs an Stayfilm erstellen

Erstellen Sie eine Webhook-Campaign, die Render-Jobs an Stayfilm übermittelt.

Wichtig

Bevor Sie die Campaign testen, bestätigen Sie, dass Stayfilm Ihr Projekt mit der Datentransformations-Callback-URL aus Schritt 2 konfiguriert hat.

1. Gehen Sie zu Messaging > Campaigns.
2. Wählen Sie Create campaign > Webhook aus.
3. Geben Sie einen Campaign-Namen ein, z. B. Stayfilm Webhook Integration.
4. Wählen Sie Compose webhook > Start from scratch aus.
5. Geben Sie unter Compose Webhook > Webhook URL die von Stayfilm bereitgestellte POST /Job-Endpunkt-URL ein. Ersetzen Sie {BASE_URL} im folgenden Beispiel: https://{BASE_URL}/stg/v3/job
6. Setzen Sie HTTP method auf POST.
7. Wählen Sie unter Request Body die Option Raw Text aus und fügen Sie dann den von Stayfilm bereitgestellten Job-Payload ein. Sie können Connected Content verwenden, um den Body dynamisch zu gestalten.

Fügen Sie CallbackRelayData ein, das auf die external_id der Braze-Nutzer:innen gesetzt ist. Stayfilm gibt diesen Wert im Callback als RelayedData zurück.

1
2
3
4
5
6
7
8
9
10
11
{
  "SmartTags": ["Setup-Template"],
  "Medias": [
    {
      "Group": "userMedia",
      "URL": "https://{BASE_URL}/some_media.png"
    }
  ],
  "Videos": [{}],
  "CallbackRelayData": "stayfilm-poc-001"
}

Fügen Sie die folgenden Anfrage-Header hinzu:

Ersetzen Sie im folgenden Connected-Content-Block {TENANT_ID}, {CLIENT_ID}, {CLIENT_SECRET_URL_ENCODED} und {SCOPE_URL_ENCODED} durch die von Stayfilm bereitgestellten Werte. URL-kodieren Sie {CLIENT_SECRET_URL_ENCODED} und {SCOPE_URL_ENCODED}, bevor Sie sie in den Block einfügen. Informationen zu den OAuth-Anforderungen finden Sie in der Stayfilm-API-Dokumentation.

1
2
3
4
5
6
7
{% connected_content https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/token
  :method post
  :body grant_type=client_credentials&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET_URL_ENCODED}&scope={SCOPE_URL_ENCODED}
  :content_type application/x-www-form-urlencoded
  :cache_max_age 3000
  :save stayfilm_auth
%}Bearer {{stayfilm_auth.access_token}}

8. Wählen Sie Save Draft aus.

Hinweis

Wenn Sie die Campaigns-Seite verlassen und zurückkehren, setzen Sie Status auf All, um Campaigns zu finden, die sich noch im Status Draft befinden.

Schritt 4: Webhook-Campaign testen

1. Wählen Sie im Webhook-Composer den Tab Test aus.
2. Wählen Sie unter Preview message as user die Option Select existing user aus und suchen Sie dann nach Ihrer Testnutzer:in (z. B. stayfilm-poc-001).
3. Wählen Sie Send test aus.

Eine erfolgreiche Antwort gibt den HTTP-Status 201 mit einem JSON-Body zurück, der dem folgenden ähnelt:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "IdJob": "4557a77e-f56c-48be-81f7-2d8c5e558cb1",
  "Videos": [
    {
      "IdVideo": "87287b25-7814-4fa1-ad1a-f2ea89822d0f",
      "IdGenre": "f07a1334-5904-420a-9f31-92644f245c5a",
      "IdVideoTemplate": "7b77c3df-12a1-4636-a9b4-bc227f4c233f",
      "IdProject": "73ea3e73-b41e-4676-b674-51731d3bf49c",
      "Status": "DRAFT_RENDERING_PENDING",
      "DurationInSeconds": null,
      "URL": null,
      "ErrorMessage": null,
      "CreatedAt": "2026-06-16T00:35:28.7736263Z",
      "UpdatedAt": "2026-06-16T00:35:28.7736264Z",
      "IdVideoFather": null,
      "IdVideoSon": null,
      "ProducingStatus": "PENDING"
    }
  ],
  "Images": []
}

Schritt 5: Stayfilm-Callback bestätigen

Stayfilm rendert das Video asynchron und sendet einen Callback an Ihre Datentransformation, wenn die Verarbeitung abgeschlossen ist. Überwachen Sie den Job-Status über die Stayfilm-API-Endpunkte, die in der Stayfilm-API-Dokumentation beschrieben sind.

1. Gehen Sie zu Data Settings > Data Transformation.
2. Wählen Sie den Tab Logs für Ihre Transformation aus.
3. Bestätigen Sie, dass ein Callback mit dem Status Success angezeigt wird.

Schritt 6: Video in einer In-App-Nachricht anzeigen

Nachdem stayfilm_video_url im Nutzerprofil befüllt ist, zeigen Sie das gerenderte Video in einer Campaign oder einem Canvas an.

1. Gehen Sie zu Messaging > Campaigns.
2. Wählen Sie Create campaign > In-app message aus.
3. Geben Sie einen Campaign-Namen ein, z. B. Stayfilm Video Show.
4. Wählen Sie im Nachrichten-Editor den Traditional Editor aus.
5. Wählen Sie unter Send To die Option Web Browsers aus.
6. Setzen Sie Message Type auf Custom Code.
7. Fügen Sie das folgende HTML in das Feld HTML ein:

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
<!doctype html>
<html>
<head>
<meta charset="UTF-8">
</head>
<body>
<div id="stayfilm-video-url" style="display: none;">{{custom_attribute.${stayfilm_video_url}}}</div>
<video id="stayfilm-video" controls preload="metadata" playsinline style="width: 100%; max-width: 420px; border-radius: 12px; background: #000;">
Your browser does not support HTML5 video.
</video>
<script>
(function () {
  var urlElement = document.getElementById("stayfilm-video-url");
  var video = document.getElementById("stayfilm-video");
  var videoUrl = urlElement ? urlElement.textContent.trim() : "";
  if (!videoUrl || videoUrl.indexOf("http") !== 0) {
    return;
  }
  var source = document.createElement("source");
  source.src = videoUrl;
  source.type = "video/mp4";
  video.appendChild(source);
  video.load();
})();
</script>
</body>
</html>

8. Wählen Sie Save Draft aus.
9. Wählen Sie den Tab Test aus.
10. Wählen Sie unter Preview message as user die Option Select existing user aus und suchen Sie dann nach der external_id Ihrer Testnutzer:in.

Das gerenderte Video wird in der Vorschau angezeigt und abgespielt, wenn stayfilm_video_url im Profil gesetzt ist.

Integration erweitern

Diese Anleitung deckt einen Teil der Stayfilm-API ab. Um Job-Templates, Medieneingaben oder nachgelagertes Messaging anzupassen, lesen Sie die Stayfilm-API-Dokumentation und aktualisieren Sie Ihren Webhook-Payload, die Datentransformations-Zuordnung und die Campaign-Logik entsprechend.

Hinweise

• Asynchrones Rendering: Die Videogenerierung erfolgt nicht sofort. Lösen Sie Folgenachrichten über das angepasste Event stayfilm_video_ready oder ein Segment basierend auf stayfilm_video_status aus, anstatt die In-App-Nachricht im selben Ablauf wie den Webhook zu senden.
• Bezeichner-Konsistenz: Der Wert in CallbackRelayData muss exakt mit der external_id der Braze-Nutzer:innen übereinstimmen.
• OAuth-Token-Caching: Das Connected-Content-Beispiel speichert das OAuth-Token für 3000 Sekunden im Cache. Passen Sie cache_max_age an, wenn Stayfilm die Anforderungen an die Token-Lebensdauer ändert.
• Sandbox-Tests: Validieren Sie den vollständigen Callback-Ablauf in einer Braze-Sandbox, bevor Sie in die Produktion gehen.
• Kapazität für angepasste Attribute: Bestätigen Sie, dass Ihr Workspace Kapazität für die angepassten Attribute und Events hat, die diese Integration erstellt.

Fehlerbehebung

Konsultieren Sie die folgende Tabelle, wenn Probleme mit der Stayfilm-Integration auftreten.