튜토리얼: 배치 ID로 배너 표시하기
이 튜토리얼의 샘플 코드를 따라 배치 ID를 사용하여 배너를 표시하세요. 더 자세한 내용은 배너를 참조하세요.
필수 조건
이 튜토리얼을 시작하기 전에 Braze SDK가 최소 버전 요구 사항을 충족하는지 확인하십시오:
웹 SDK용 배너 표시
1. 디버깅 활성화 (선택 사항) {#1-enable-debugging-optional}
개발 중 문제 해결을 더 쉽게 하려면 디버깅 활성화를 고려하세요.
2. 배너 이벤트 구독 {#2-subscribe-to-banner-events}
웹 SDK 7.0.0 이상에서 subscribeToBannersEvents()를 사용하여 핸들러를 등록합니다. 핸들러는 배너 캐시가 재생, 다시 로드 또는 업데이트되거나 오류가 발생할 때 실행됩니다. 핸들러 내부에서 event.cacheSnapshot.banners로부터 배치를 읽어옵니다. subscribeToBannersUpdates()는 이전 패턴으로, 7.0.0부터 더 이상 사용되지 않습니다. 전체 이벤트 목록은 이벤트 구독을 참조하세요.
3. 배너 삽입 및 대조군 처리 {#3-insert-the-banner-and-handle-control-groups}
braze.insertBanner(banner, container)를 사용하여 배너가 반환될 때 삽입합니다. 레이아웃을 깔끔하게 유지하려면 대조군에 포함된 배너를 숨기거나 접습니다(예: isControl이 true인 경우).
4. 배너 새로고침 {#4-refresh-your-banners}
SDK를 초기화한 후 requestBannersRefresh(["global_banner", ...])를 호출하여 각 세션 시작 시 배너가 새로고침되도록 합니다.
이 함수는 언제든지 호출하여 배너 배치를 나중에 새로고침할 수도 있습니다.
5. 배너 컨테이너 추가 {#5-add-a-container-for-your-banner}
HTML에서 새 <div> 요소를 추가하고 global-banner-container와 같이 배너와 관련된 짧은 id를 지정합니다. Braze는 이 <div>를 사용하여 배너를 페이지에 삽입합니다.
필수 조건
이 튜토리얼을 시작하기 전에 Braze SDK가 최소 버전 요구 사항을 충족하는지 확인하십시오:
Android SDK용 배너 표시
1. 디버깅 활성화(선택 사항) {#1-enable-debugging-optional}
개발 중 문제 해결을 더 쉽게 하려면 디버깅을 활성화하는 것이 좋습니다.
2. 배너 이벤트 구독 {#2-subscribe-to-banner-events}
subscribeToBannersEvents()를 사용하여 배너 캐시가 재생되거나 업데이트될 때 실행되는 핸들러를 등록합니다. BannersCacheSnapshot.banners는 배치 ID와 Banner를 매핑한 맵입니다.
수신할 수 있는 이벤트의 전체 목록은 이벤트 구독을 참조하세요.
3. banners.xml에서 BannerView 정의 {#3-define-bannerview-in-your-bannersxml}
banners.xml에서 app:placementId="PLACEMENT_ID"를 사용하여 <com.braze.ui.banners.BannerView>를 선언하고 android:layout_height를 0dp로 설정합니다. 이 뷰는 배너가 콘텐츠 높이를 보고할 때까지 높이 없이 레이아웃에 남아 있으므로, 배너가 로드되기 전에 화면에 빈 공간이 생기지 않습니다.
새로고침 후 SDK는 해당 배치의 콘텐츠가 변경된 경우에만 BannerView를 업데이트합니다. 변경되지 않은 표시 중인 배너는 그대로 유지됩니다.
4. 배너 높이 업데이트 {#4-update-the-banner-height}
BannerView에 heightCallback을 설정합니다. 콜백은 배너 높이를 dp 단위로 받습니다. 이 높이는 직접 뷰에 적용해야 합니다. dp를 픽셀로 변환한 다음 레이아웃 높이를 설정하세요.
배너 HTML은 JavaScript 인터페이스를 통해 높이를 보고하므로 heightCallback이 메인 스레드가 아닌 곳에서 실행될 수 있습니다. 변경 사항이 메인 스레드에서 실행되도록 bannerView.post 내부에서 뷰를 업데이트하세요.
높이가 0.0이면 표시할 콘텐츠가 없다는 뜻입니다. SDK는 배치에 배너가 없거나, 배너가 대조군에 속하거나, 배너가 닫힌 경우 0.0을 보고합니다. 이 경우에도 0.0을 적용하면 뷰가 축소되어 다음 배너를 위해 레이아웃에 남아 있게 됩니다.
5. 배너 높이 제한 {#5-limit-the-banner-height}
적용할 높이에 상한을 설정합니다. 이 예시에서는 min(heightDp, 80.0)을 사용하여 배너 높이를 80 dp 이하로 유지합니다.
6. 배치 새로고침 {#6-refresh-your-placements}
Braze SDK를 초기화한 후 requestBannersRefresh(["PLACEMENT_ID"])를 호출하여 해당 배치의 최신 배너 콘텐츠를 가져옵니다.
이 호출은 기존 배너 캐시에 병합됩니다. 요청한 배치 ID만 추가, 업데이트 또는 제거됩니다. 다른 배치의 캐시된 배너는 캐시에 그대로 남아 있다가 원래 만료 시간에 만료됩니다. 서버가 요청한 배치에 대해 배너를 반환하지 않으면 해당 배치는 캐시에서 삭제됩니다.
Jetpack Compose를 사용하려면 앱 모듈에 com.braze:android-sdk-jetpack-compose 아티팩트를 추가하세요. 다른 Braze Android SDK 종속성과 동일한 버전을 사용해야 합니다.
1. 디버깅 활성화(선택 사항)
개발 중 문제 해결을 더 쉽게 하려면 디버깅을 활성화하는 것이 좋습니다.
2. 배너 이벤트 구독
subscribeToBannersEvents를 호출하고, 컴포저블이 화면을 벗어날 때 제거할 수 있도록 구독자를 보관해 둡니다. CacheReplay, CacheLoad 또는 DataUpdated에 이 배치가 포함되어 있으면 hasBannerForPlacement를 설정합니다. FeatureDisabled와 함께 ErrorEvent가 발생하면 hasBannerForPlacement를 false로 설정합니다.
배너 이벤트는 백그라운드 스레드에서 도착합니다. UI 업데이트는 메인 스레드에 게시하세요.
각 이벤트가 발생하는 시점은 이벤트 구독을 참조하세요.
3. 배치 새로고침 {#3-refresh-your-placements}
구독자를 등록한 후 requestBannersRefresh(["PLACEMENT_ID"])를 호출하여 해당 배치의 최신 배너 콘텐츠를 가져옵니다. 더 이상 필요하지 않으면 removeSingleSubscription으로 구독자를 제거하세요.
4. 캐시에 배너가 있을 때만 배너 표시 {#4-only-show-the-banner-after-it-is-in-the-cache}
hasBannerForPlacement가 true일 때만 Banner를 표시합니다. 캐시에 해당 배치의 배너가 포함될 때까지 배치는 레이아웃에 나타나지 않습니다.
com.braze.jetpackcompose.banners.Banner를 가져오세요. 다른 Compose 라이브러리에도 자체 Banner 컴포저블이 정의되어 있습니다.
5. 배너 높이 업데이트 {#5-update-the-banner-height}
Banner에 heightCallback을 전달합니다. 콜백은 배너 높이를 dp 단위로 받습니다. 이 값을 contentHeight에 저장하고 Modifier.height로 적용합니다. Banner는 크기 조정을 레이아웃에 맡깁니다.
heightCallback은 메인 스레드가 아닌 곳에서 실행될 수 있습니다. contentHeight를 변경하기 전에 상태 업데이트를 메인 스레드에 게시하세요.
높이가 0.0이면 표시할 콘텐츠가 없다는 뜻이며, UI에 빈 공간이 생기지 않도록 합니다. SDK는 배치에 배너가 없거나, 배너가 대조군에 속하거나, 배너가 닫힌 경우 0.0을 보고합니다.
6. 배너 높이 제한 {#6-limit-the-banner-height}
적용할 높이에 상한을 설정합니다. 이 예시에서는 min(contentHeight, 80.0)을 사용하여 배너 높이를 80 dp 이하로 유지합니다.
필수 조건
이 튜토리얼을 시작하기 전에 Braze SDK가 최소 버전 요구 사항을 충족하는지 확인하십시오:
Swift SDK용 배너 표시
1. 디버깅 활성화(선택 사항) {#1-enable-debugging-optional} {#1-enable-debugging-optional}
개발 중 문제 해결을 쉽게 하기 위해 디버깅을 활성화하는 것을 고려하세요.
2. 배너 이벤트 구독 {#2-subscribe-to-banner-events} {#2-subscribe-to-banner-events}
subscribeToEvents를 사용하여 배너 캐시가 리플레이, 다시 로드 또는 업데이트되거나 오류가 발생할 때 실행되는 핸들러를 등록합니다. cacheSnapshot.banners는 배치 ID를 Banner에 매핑하는 사전입니다. 반환된 Braze.Cancellable에 대한 강한 참조를 유지하세요. SDK는 해제될 때 가입을 취소합니다.
각 이벤트가 실행되는 시점에 대해서는 이벤트 구독을 참조하세요.
3. 배치 새로고침 {#3-refresh-your-placements} {#3-refresh-your-placements}
가입을 등록한 후 requestBannersRefresh(placementIds: ["PLACEMENT_ID"])를 호출하여 각 세션 시작 시 배너 콘텐츠를 새로고침합니다.
4. 배너 초기화 및 콜백 제공 {#4-initialize-the-banner-and-provide-a-callback} {#4-initialize-the-banner-and-provide-a-callback}
Braze 객체와 배치 ID로 BrazeBannerUI.BannerUIView 인스턴스를 생성하고, 제공된 콘텐츠 높이에 따라 배너를 표시하고 높이 제약 조건을 업데이트하는 processContentUpdates 콜백을 제공합니다.
5. Auto Layout 제약 조건 활성화 {#5-enable-auto-layout-constraints} {#5-enable-auto-layout-constraints}
기본적으로 배너 뷰를 숨긴 다음 자동 크기 조정 마스크 변환을 비활성화하여 Auto Layout 제약 조건을 활성화합니다.
6. 콘텐츠 앵커 및 높이 제약 조건 설정 {#6-anchor-content-and-set-height-constraints} {#6-anchor-content-and-set-height-constraints}
Auto Layout을 사용하여 메인 콘텐츠를 상단에 앵커링하고, 그 아래에 배너 뷰를 배치합니다. 배너의 앞, 뒤, 하단 가장자리를 안전 영역에 고정하고 콘텐츠가 로드될 때 업데이트될 초기 높이 제약 조건을 0으로 설정합니다.
1. 디버깅 활성화(선택 사항) {#1-enable-debugging-optional}
개발 중 문제 해결을 쉽게 하기 위해 디버깅을 활성화하는 것을 고려하세요.
2. 배치 새로고침 {#2-refresh-your-placements} {#2-refresh-your-placements}
Braze SDK를 초기화한 후 requestBannersRefresh(placementIds: ["PLACEMENT_ID"])를 호출하여 각 세션 시작 시 배너 콘텐츠를 새로고침합니다.
3. 뷰 컴포넌트 생성 {#3-create-a-view-component} {#3-create-a-view-component}
사용 가능한 배너를 표시하고 필요한 경우 메인 앱 콘텐츠를 포함하는 재사용 가능한 SwiftUI 뷰 컴포넌트를 생성합니다.
4. 배너 이벤트 구독 {#4-subscribe-to-banner-events} {#4-subscribe-to-banner-events}
.onAppear에서 subscribeToEvents를 사용하여 배너 캐시가 리플레이, 다시 로드 또는 업데이트될 때마다 hasBannerForPlacement를 설정하는 핸들러를 등록합니다. SDK는 해제될 때 가입을 취소하므로, 반환된 Braze.Cancellable에 대한 강한 참조를 상태에 유지하세요.
각 이벤트가 실행되는 시점에 대해서는 이벤트 구독을 참조하세요.
5. 로드 후에만 BannerView 표시 {#5-only-show-bannerview-after-it-loads} {#5-only-show-bannerview-after-it-loads}
UI에 빈 공간이 생기지 않도록, 배너가 존재하고 SDK가 초기화된 경우에만 BrazeBannerUI.BannerView를 표시합니다.
6. 배너 높이 동적 업데이트 {#6-dynamically-update-banner-height} {#6-dynamically-update-banner-height}
processContentUpdates 콜백을 사용하여 배너 콘텐츠가 로드되는 즉시 높이를 가져옵니다. SwiftUI 상태(contentHeight)를 업데이트하고 제공된 높이를 사용하여 .frame(height:) 제약 조건을 적용합니다.
7. 배너 높이 제한 {#7-limit-the-banner-height} {#7-limit-the-banner-height}
배너가 최대 높이를 초과하지 않도록 .frame(height: min(contentHeight, 80)) 수정자를 적용합니다. 이렇게 하면 배너 콘텐츠에 관계없이 UI가 시각적으로 균형 잡힌 상태를 유지합니다.