Stayfilm

Stayfilm은 대규모 자동화된 개인화 비디오 제작을 위한 REST API입니다. 이 플랫폼은 데이터, 이미지, 텍스트, 사운드트랙, 내레이션, 시각 효과를 통합하여 이커머스, 마켓플레이스, CRM 워크플로, 마케팅 Campaign을 위한 맞춤형 비디오 콘텐츠를 생성합니다.

이 통합은 Braze에서 Stayfilm API로 렌더 작업을 전송하고, 비디오가 준비되면 콜백을 수신하며, Campaign 및 Canvases에서 사용할 수 있도록 비디오 URL과 상태를 고객 프로필에 저장합니다.

이 통합은 Stayfilm에서 유지 관리합니다.

사용 사례

Stayfilm은 다음을 포함하여 고객 생애주기 전반에 걸쳐 개인화된 비디오 전달을 지원합니다:

• 온보딩 및 환영 여정: 프로필이나 가입 맥락에 맞게 개인화된 비디오로 신규 사용자를 환영합니다
• 제품 및 마켓플레이스 콘텐츠: 카탈로그 또는 사용자 제공 미디어에서 제품 중심 비디오를 생성합니다
• 전환 및 활성화: 상황별 비디오 메시징으로 주요 행동을 강화합니다
• 로열티 및 업셀: 개인화된 오퍼 또는 사용 마일스톤을 비디오 형식으로 강조합니다
• 윈백 및 고객이탈 방지: 맞춤형 비디오 콘텐츠로 비활성 사용자를 다시 참여시킵니다

전제 조건

시작하기 전에 다음 사항을 확인하세요:

통합 작동 방식

이 통합은 양방향 웹훅 흐름을 사용합니다:

1. 아웃바운드: Braze 웹훅 Campaign이 Stayfilm POST /Job 엔드포인트로 렌더 작업을 전송합니다. 요청에는 사용자 미디어, 템플릿 구성, Braze 사용자의 external_id로 설정된 CallbackRelayData가 포함됩니다.
2. 인바운드: Stayfilm이 렌더링을 완료하면 Braze 데이터 변환 웹훅 URL로 콜백을 전송합니다. 변환은 응답을 일치하는 고객 프로필의 커스텀 속성 및 커스텀 이벤트에 매핑합니다.
3. 전달: 저장된 stayfilm_video_url 속성을 커스텀 HTML이 포함된 인앱 메시지 등의 메시징 채널에서 사용합니다.

이 안내서의 데이터 변환은 다음 커스텀 속성을 기록합니다:

변환은 또한 stayfilm_video_ready 또는 stayfilm_video_failed라는 이름의 커스텀 이벤트를 기록합니다.

통합

다음 단계는 개념 증명을 안내합니다. 흐름을 검증한 후 작업 페이로드, 속성, 메시징을 사용 사례에 맞게 조정하세요.

1단계: 테스트 사용자 만들기

통합을 구축하고 검증하는 동안 사용할 테스트 사용자 프로필을 만드세요. 자세한 내용은 사용자 가져오기를 참조하세요.

1. 오디언스 > 사용자 가져오기로 이동합니다.
2. 빠른 사용자 추가를 선택합니다.
3. external_id와 기타 필수 필드를 입력한 다음 새 사용자 만들기를 선택합니다.

중요

이메일, 전화번호, 성명, 정부 발급 ID, 주소, 주문 세부 정보 등 개인 데이터를 external_id로 사용하지 마세요. 이 통합 전체에서 external_id를 대소문자 구분으로 처리하세요.

이 안내서에서는 stayfilm-poc-001을 예시 external_id로 사용합니다. 이후 단계에서 사용하므로 선택한 값을 기록해 두세요.

2단계: 데이터 변환 만들기

Stayfilm 콜백을 수신하고 고객 프로필을 업데이트하기 위한 데이터 변환을 만드세요.

1. 데이터 설정 > 데이터 변환으로 이동합니다.
2. 변환 만들기를 선택합니다.
3. Stayfilm Callback Data Transformation과 같은 이름을 입력합니다.
4. 편집 환경에서 처음부터 시작을 선택합니다.
5. 대상 선택 > 대상에서 POST: Track users를 선택합니다.
6. 변환 만들기를 선택합니다.
7. 기본 변환 코드를 다음으로 교체합니다:

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. 저장을 선택한 다음 생성된 웹훅 URL을 복사합니다.
9. 다음 샘플 Stayfilm 콜백 JSON으로 웹훅 URL에 테스트 POST 요청을 보냅니다. RelayedData를 1단계에서 만든 테스트 사용자의 external_id로 설정합니다.

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

cURL, Postman 또는 유사한 도구로 요청을 보냅니다. 성공적인 응답은 {"message": "success"}와 함께 HTTP 상태 201을 반환합니다.

10. 데이터 설정 > 데이터 변환으로 이동하고, 변환이 목록에 나타나지 않으면 페이지를 새로고침합니다.
11. 변환을 열고 검증을 선택합니다. 출력에서 검증이 성공했는지 확인합니다.
12. 활성화를 선택합니다.
13. 복사한 웹훅 URL을 콜백 URL로 Stayfilm에 제공합니다.

참고

CallbackRelayData에 Braze external_id 외에 추가 데이터를 저장하는 경우, RelayedData를 적절히 파싱하도록 변환 코드를 업데이트하세요.

3단계: Stayfilm에 작업을 전송하는 웹훅 Campaign 만들기

Stayfilm에 렌더 작업을 제출하는 웹훅 Campaign을 만드세요.

중요

Campaign을 테스트하기 전에 Stayfilm이 2단계의 데이터 변환 콜백 URL로 프로젝트를 구성했는지 확인하세요.

1. 메시징 > Campaigns로 이동합니다.
2. Campaign 만들기 > 웹훅을 선택합니다.
3. Stayfilm Webhook Integration과 같은 Campaign 이름을 입력합니다.
4. 웹훅 작성 > 처음부터 시작을 선택합니다.
5. 웹훅 작성 > 웹훅 URL에 Stayfilm이 제공한 Stayfilm POST /Job 엔드포인트 URL을 입력합니다. 다음 예시에서 {BASE_URL}을 교체합니다: https://{BASE_URL}/stg/v3/job
6. HTTP 메서드를 POST로 설정합니다.
7. 요청 본문에서 Raw Text를 선택한 다음 Stayfilm이 제공하는 작업 페이로드를 붙여넣습니다. 연결된 콘텐츠를 사용하여 본문을 동적으로 만들 수 있습니다.

Braze 사용자의 external_id로 설정된 CallbackRelayData를 포함합니다. Stayfilm은 콜백에서 이 값을 RelayedData로 반환합니다.

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

다음 요청 헤더를 추가합니다:

다음 연결된 콘텐츠 블록에서 {TENANT_ID}, {CLIENT_ID}, {CLIENT_SECRET_URL_ENCODED}, {SCOPE_URL_ENCODED}를 Stayfilm이 제공하는 값으로 교체합니다. {CLIENT_SECRET_URL_ENCODED}와 {SCOPE_URL_ENCODED}는 블록에 붙여넣기 전에 URL 인코딩하세요. OAuth 요구 사항은 Stayfilm API 설명서를 참조하세요.

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. 초안 저장을 선택합니다.

참고

Campaigns 페이지를 떠났다가 돌아오는 경우, 상태를 전체로 설정하여 아직 초안 상태인 Campaign을 찾으세요.

4단계: 웹훅 Campaign 테스트

1. 웹훅 작성기에서 테스트 탭을 선택합니다.
2. 사용자로 메시지 미리보기에서 기존 사용자 선택을 선택한 다음 테스트 사용자(예: stayfilm-poc-001)를 검색합니다.
3. 테스트 전송을 선택합니다.

성공적인 응답은 다음과 유사한 JSON 본문과 함께 HTTP 상태 201을 반환합니다:

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": []
}

5단계: Stayfilm 콜백 확인

Stayfilm은 비디오를 비동기적으로 렌더링하고 처리가 완료되면 데이터 변환으로 콜백을 전송합니다. Stayfilm API 설명서에 설명된 Stayfilm API 엔드포인트를 통해 작업 상태를 모니터링하세요.

1. 데이터 설정 > 데이터 변환으로 이동합니다.
2. 변환의 로그 탭을 선택합니다.
3. 성공 상태의 콜백이 나타나는지 확인합니다.

6단계: 인앱 메시지에 비디오 표시

고객 프로필에 stayfilm_video_url이 채워진 후 Campaign 또는 Canvas에서 렌더링된 비디오를 표시합니다.

1. 메시징 > Campaigns로 이동합니다.
2. Campaign 만들기 > 인앱 메시지를 선택합니다.
3. Stayfilm Video Show와 같은 Campaign 이름을 입력합니다.
4. 메시지 작성기에서 기존 편집기를 선택합니다.
5. 전송 대상에서 웹 브라우저를 선택합니다.
6. 메시지 유형을 커스텀 코드로 설정합니다.
7. 다음 HTML을 HTML 필드에 붙여넣습니다:

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. 초안 저장을 선택합니다.
9. 테스트 탭을 선택합니다.
10. 사용자로 메시지 미리보기에서 기존 사용자 선택을 선택한 다음 테스트 사용자의 external_id를 검색합니다.

프로필에 stayfilm_video_url이 설정되어 있으면 렌더링된 비디오가 미리보기에 나타나고 재생됩니다.

통합 확장

이 안내서는 Stayfilm API의 일부만 다룹니다. 작업 템플릿, 미디어 입력 또는 다운스트림 메시징을 조정하려면 Stayfilm API 설명서를 참조하고 웹훅 페이로드, 데이터 변환 매핑, Campaign 로직을 적절히 업데이트하세요.

고려 사항

• 비동기 렌더링: 비디오 생성은 즉시 이루어지지 않습니다. 웹훅과 동일한 흐름에서 인앱 메시지를 보내는 대신 stayfilm_video_ready 커스텀 이벤트 또는 stayfilm_video_status 기반 Segment에서 후속 메시징을 트리거하세요.
• 식별자 일관성: CallbackRelayData의 값은 Braze 사용자의 external_id와 정확히 일치해야 합니다.
• OAuth 토큰 캐싱: 연결된 콘텐츠 예시는 OAuth 토큰을 3000초 동안 캐싱합니다. Stayfilm이 토큰 수명 요구 사항을 변경하면 cache_max_age를 조정하세요.
• 샌드박스 테스트: 프로덕션 출시 전에 Braze 샌드박스에서 전체 콜백 루프를 검증하세요.
• 커스텀 속성 용량: 이 통합이 생성하는 Stayfilm 커스텀 속성 및 이벤트에 대한 워크스페이스 용량이 충분한지 확인하세요.

문제 해결

Stayfilm 통합에 문제가 발생하면 다음 표를 참조하세요.