Contentful

Contentful은 팀이 구조화된 콘텐츠를 생성, 관리하고 모든 채널에 배포할 수 있는 헤드리스 콘텐츠 관리 시스템입니다. Contentful용 Braze 앱은 해당 콘텐츠를 Braze 메시징에 직접 연결합니다. 연결된 콘텐츠를 사용하여 발송 시점에 Contentful 항목을 메시지에 동적으로 가져오거나, 선택한 필드를 Braze Content Blocks에 동기화하여 Campaigns와 Canvases 전반에서 재사용할 수 있습니다.

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

이 통합에 대해

이 페이지에서는 Contentful에서 Braze 앱을 구성하는 방법과 Braze에서 Contentful 자산을 사용하는 방법을 다룹니다. 이 통합을 통해 다음을 수행할 수 있습니다.

• 게시된 항목에 대해 바로 붙여넣기 가능한 Braze 연결된 콘텐츠 호출을 생성하고, Braze 메시지에서 각 필드를 참조하는 데 필요한 Liquid 태그를 함께 생성합니다.
• 선택한 로케일과 함께 항목의 특정 필드를 Braze 콘텐츠 블록에 동기화하여, Braze 대시보드에서 콘텐츠를 기본적으로 사용할 수 있도록 합니다.

그 결과 콘텐츠에 대한 단일 진실 공급원(Single Source of Truth)이 만들어집니다. 콘텐츠 편집자는 기존의 검토 및 현지화 워크플로를 통해 Contentful에서 계속 작업하고, 마케터는 이미 승인되고 최신 상태인 콘텐츠를 기반으로 Braze에서 캠페인을 구축합니다.

사전 요구 사항

시작하기 전에 다음이 필요합니다.

요구 사항	설명
Contentful 계정	앱을 설치할 스페이스에 대한 Space Admin 액세스 권한이 있는 Contentful 계정.
Contentful API 키	읽기 액세스 권한이 있는 Contentful Content Delivery API(CDA) 키. Contentful에서 Settings > API keys로 이동하여 생성합니다.
Braze REST API 키	content_blocks.create, content_blocks.update, content_blocks.info, content_blocks.list 권한이 있는 Braze REST API 키. Braze 대시보드에서 Settings > APIs and Identifiers > API Keys로 이동하여 이 키를 생성합니다. Content Blocks 동기화에만 필요합니다.
Braze REST 엔드포인트	Braze REST 엔드포인트 URL. 엔드포인트는 인스턴스의 Braze URL에 따라 다릅니다. Content Blocks 동기화에만 필요합니다.

연동

1단계: Contentful에 Braze 앱 설치

1. Contentful 웹 앱에 로그인합니다.
2. Apps > Marketplace를 선택합니다.
3. Braze 앱을 찾아 선택합니다.
4. Install을 선택합니다. Manage app access 창이 나타납니다.
5. Environments 아래에서 앱을 설치할 환경을 선택합니다.
6. Authorize access를 선택합니다. 앱 구성 화면이 나타납니다.
7. Contentful API key에 Content Delivery API 키를 입력합니다.
8. Content Blocks 동기화를 활성화하려면 Braze REST API 키를 입력하고 Braze REST 엔드포인트를 선택합니다.
9. Install to selected environments를 선택합니다.

2단계: 콘텐츠 유형에 Braze 앱 추가

1. Contentful 웹 앱에서 Content model 탭으로 이동합니다.
2. 기존 콘텐츠 유형을 선택하거나 새로 만듭니다.
3. Sidebar 섹션으로 스크롤합니다.
4. 사용 가능한 항목 목록에서 Braze를 추가합니다.
5. Save를 선택합니다.

Braze에서 사용할 각 콘텐츠 유형에 대해 이 과정을 반복합니다.

3단계: 항목을 Braze에 연결

1. Content 탭으로 이동하여 Add entry를 선택하고, 사이드바에 Braze 앱이 포함된 콘텐츠 유형을 선택합니다. 기존 항목을 열 수도 있습니다.
2. 항목 필드를 채우고 항목을 게시(publish)합니다. Braze는 게시된 콘텐츠만 가져올 수 있습니다.
3. 항목 사이드바에서 Generate Braze Connected Content를 선택하여 Braze 메시지에 붙여넣을 연결된 콘텐츠 호출 및 Liquid 태그를 생성하거나, Create Content Block을 선택하여 선택한 필드를 Braze에 Content Blocks로 푸시합니다.

Content Blocks 동기화

1단계: 항목을 Braze Content Block에 동기화

1. 사이드바에 Braze 앱이 있는 게시된 항목을 엽니다.
2. 사이드바에서 Create Content Block을 선택합니다.
3. 사용할 로케일을 선택합니다. 선택한 로케일당 하나의 Content Block이 생성됩니다.
4. Content Block에 포함할 필드를 선택합니다.
5. Send to Braze를 선택합니다. Braze 워크스페이스에 Content Block이 생성되며, 콘텐츠 > Content Block에서 사용할 수 있습니다.

2단계: 동기화된 콘텐츠를 최신 상태로 유지

콘텐츠가 변경되는 빈도에 맞는 방법을 선택하세요:

• Content Block 동기화는 전송 시점에 안정적이고 여러 메시지에서 재사용되는 콘텐츠에 적합합니다. 외부 호출 없이 렌더링됩니다.
• 연결된 콘텐츠는 Campaign이 작성된 시점과 전달되는 시점 사이에 콘텐츠가 변경될 수 있는 경우에 적합합니다. 전달 시점에 콘텐츠를 가져오기 때문입니다.

Contentful의 Braze 앱 작동 방식에 대한 자세한 내용은 Contentful의 Braze 앱 설명서를 참조하세요.

연결된 콘텐츠 사용

1단계: Braze 메시지에 연결된 콘텐츠 호출 추가

1. Contentful에서 게시된 항목을 열고 사이드바에서 Generate Braze Connected Content를 선택합니다.
2. 포함할 필드를 선택한 다음 Next를 선택합니다.
3. 항목에 여러 로케일이 있는 경우 포함할 로케일을 선택한 다음 Next를 선택합니다.
4. 생성된 연결된 콘텐츠 호출을 복사합니다.
5. Braze에서 Campaign 또는 Canvas 메시지를 생성하거나 엽니다.
6. 메시지 본문 상단에 연결된 콘텐츠 호출을 붙여넣습니다.
7. 콘텐츠가 표시될 위치에 Liquid 태그를 붙여넣습니다.

2단계: Liquid를 사용하여 필드 참조

JSON 점 표기법을 사용하면 Contentful의 응답 본문에서 메시지에 포함할 부분을 지정할 수 있습니다. 이는 사용 사례에 따라 달라집니다. 앱은 각 필드에 대해 올바른 Liquid 태그를 생성합니다. 항목이 현지화된 경우 태그는 로케일별로 네임스페이스가 지정되고, 현지화되지 않은 경우 콘텐츠 유형별로 네임스페이스가 지정됩니다.

시나리오	Liquid 태그 예시
현지화된 항목 (en-US)	{{response.data.enUS.body}}
현지화된 항목 (es-AR)	{{response.data.esAR.body}}
현지화되지 않은 항목	{{response.data.blogPost.body}}
짧은 텍스트 목록, 결합	{{response.data.recipe.ingredients | join: ', '}}
짧은 텍스트 목록, 단일 항목	{{response.data.recipe.ingredients[0]}}
위치 필드	{{response.data.venue.address.lat}} 및 {{response.data.venue.address.lon}}
단일 미디어 파일	{{response.data.blogPost.image.url}}
에셋 컬렉션, 단일 항목	{{response.data.blogPost.imagesCollection.items[0].url}}
다중 참조, 단일 항목	{{response.data.event.contactList[0].name}}
다중 참조, 반복	{% for contact in response.data.event.contactList %} {{contact.name}} {% endfor %}

미디어 필드는 url 외에도 title, description, contentType, fileName, size, width, height를 노출합니다.

3단계: 미리보기 및 전송

1. Braze의 Preview & Test 탭을 사용하여 연결된 콘텐츠 호출이 정상적으로 해석되고 Liquid 태그가 예상 값을 렌더링하는지 확인합니다.
2. 본인 또는 테스트 사용자에게 테스트 메시지를 발송합니다.
3. 콘텐츠가 올바르게 렌더링된 후 Campaign 또는 Canvas를 실행합니다.

고려 사항

• 항목은 게시된 상태여야 합니다. Braze는 Content Delivery API를 통해 콘텐츠를 가져오며, 이 API는 게시된 항목만 반환합니다. 초안이거나 변경 후 게시되지 않은 항목은 렌더링되지 않습니다.
• 연결된 콘텐츠는 전송 시점에 요청을 추가합니다. 콘텐츠는 각 메시지가 전달될 때 가져옵니다. 요청이 실패할 경우 캐싱, 타임아웃 및 메시지 중단에 대한 연결된 콘텐츠 가이드를 따르고, Contentful 플랜의 API 사용량 제한이 전송 볼륨을 감당할 수 있는지 확인하세요. Contentful의 사용량 제한에 대해서는 Contentful 기술 제한을 참조하세요.
• Content Blocks는 워크스페이스별로 적용됩니다. Contentful에서 동기화된 Content Blocks는 구성한 REST API 키에 연결된 Braze 워크스페이스에 생성됩니다. 다른 워크스페이스에서 동일한 콘텐츠를 사용하려면 해당 워크스페이스에 대해서도 앱을 구성하세요.
• 로케일은 별도의 출력을 생성합니다. 여러 로케일을 선택하면 로케일별로 별도의 Liquid 태그(연결된 콘텐츠) 또는 별도의 Content Blocks(동기화)가 생성됩니다.

문제 해결

문제	해결 방법
설치 중 “A valid Contentful API key is required” 오류 발생	해당 키가 읽기 권한이 있는 Content Delivery API(CDA) 키인지, 설치하려는 스페이스에 속한 키인지 확인하세요.
Braze 미리보기에서 Liquid 태그가 비어 있는 상태로 렌더링됨	항목이 게시되었는지, 필드에 콘텐츠가 있는지, 태그의 로케일이 항목에 설정된 로케일과 일치하는지 확인하세요.
Braze에서 연결된 콘텐츠 호출이 오류를 반환함	생성된 호출에서 스페이스 ID, 환경 및 액세스 토큰을 확인하고 엔드포인트를 직접 테스트하세요. Braze는 연결된 콘텐츠 오류를 메시지 활동 로그에 기록합니다.
콘텐츠 블록이 Braze에 표시되지 않음	Braze REST API 키에 필요한 콘텐츠 블록 권한이 있는지, REST 엔드포인트가 Braze 인스턴스와 일치하는지 확인하세요.
참조 목록의 필드가 빈 값을 반환함	목록에 여러 콘텐츠 유형이 포함되어 있는지 확인하고, 인덱스로 접근하는 대신 목록을 반복(loop)하여 처리하세요.

추가 리소스

• Contentful 도움말 센터의 Braze 앱 가이드
• Contentful 마켓플레이스의 Braze 앱 목록
• Contentful Content Delivery API 설명서
• Braze 연결된 콘텐츠
• Braze Content Blocks