チュートリアル: プレースメントIDによるバナーの表示
このチュートリアルのサンプルコードに沿って、プレースメントIDを使用してバナーを表示します。詳細については、バナーを参照してください。
前提条件
このチュートリアルを始める前に、Braze SDKが最低バージョン要件を満たしていることを確認してください：
Web SDKのバナーを表示する
1. デバッグを有効にする（任意） {#1-enable-debugging-optional} {#1-enable-debugging-optional}
開発中のトラブルシューティングを容易にするために、デバッグの有効化を検討してください。
2. バナーイベントを購読する {#2-subscribe-to-banner-events} {#2-subscribe-to-banner-events}
Web SDK 7.0.0以降では、subscribeToBannersEvents() を使用してハンドラーを登録します。ハンドラーは、バナーキャッシュがリプレイ、再読み込み、または更新されたとき、あるいはエラーが発生したときに実行されます。ハンドラー内では、event.cacheSnapshot.banners からプレースメントを読み取ります。subscribeToBannersUpdates() は以前のパターンであり、7.0.0で非推奨になりました。イベントの全一覧については、イベント購読を参照してください。
3. バナーを挿入してコントロールグループを処理する {#3-insert-the-banner-and-handle-control-groups} {#3-insert-the-banner-and-handle-control-groups}
braze.insertBanner(banner, container) を使用して、バナーが返されたときにバナーを挿入します。レイアウトを整った状態に保つため、コントロールグループに含まれるバナー（例えば、isControl が true の場合）は非表示にするか折りたたんでください。
4. バナーを更新する {#4-refresh-your-banners} {#4-refresh-your-banners}
SDKを初期化した後、requestBannersRefresh(["global_banner", ...]) を呼び出して、各セッションの開始時にバナーが更新されるようにします。
また、この関数はいつでも呼び出して、後からバナープレースメントを更新することもできます。
5. バナー用のコンテナを追加する {#5-add-a-container-for-your-banner} {#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へのディクショナリです。SDKはBraze.Cancellableがデアロケートされると購読をキャンセルするため、返されたBraze.Cancellableへの強参照を保持してください。
各イベントがいつ発火するかについては、イベント購読を参照してください。
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制約を有効にするためにautoresizingマスクの変換を無効にします。
6. コンテンツをアンカーし高さ制約を設定する {#6-anchor-content-and-set-height-constraints} {#6-anchor-content-and-set-height-constraints}
Auto Layoutを使用してメインコンテンツを上部にアンカーし、その後にバナービューを配置します。バナーのleading、trailing、bottomエッジをセーフエリアにピン留めし、コンテンツ読み込み時に更新される初期高さ制約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がデアロケートされると購読をキャンセルするため、返された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の視覚的なバランスが保たれます。