Content Cards

注

このガイドでは、Braze Web SDK 4.0.0+ のコードサンプルを使用します。最新の Web SDK バージョンにアップグレードするには、SDK アップグレードガイドを参照してください。

前提条件

Content Cardsを使用する前に、アプリにBraze Web SDKを統合する必要があります。ただし、追加の設定は不要です。独自のUIを構築する場合は、Content Cardsカスタマイズガイドを参照してください。

注

一部の広告ブロッカーやブラウザのプライバシー拡張機能は、Braze Web SDKのスクリプトや関連するネットワークリクエストをブロックし、Content Cardsの読み込みを妨げる場合があります。CDN統合方式を使用している場合は、NPM統合方式への切り替えを検討してください。この方式ではSDKライブラリがWebサイト上にローカルで保存されるため、広告ブロッカーに関連する一部の問題を回避できます。

標準フィードUI

組み込みのContent Cards UIを使用するには、Webサイト上でフィードを表示する場所を指定する必要があります。

この例では、Content Cardsフィードを配置する <div id="feed"></div> を用意しています。フィードの非表示、表示、またはトグル（現在の状態に基づいて非表示または表示）を行うための3つのボタンを使用します。

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

<button id="toggle" type="button">Toggle Cards Feed</button>
<button id="hide" type="button">Hide Cards Feed</button>
<button id="show" type="button">Show Cards Feed</button>

<nav>
    <h1>Your Personalized Feed</h1>
    <div id="feed"></div>
</nav>

<script>
   const toggle = document.getElementById("toggle");
   const hide = document.getElementById("hide");
   const show = document.getElementById("show");
   const feed = document.getElementById("feed");

   toggle.onclick = function(){
      braze.toggleContentCards(feed);
   }

   hide.onclick = function(){
      braze.hideContentCards();
   }

   show.onclick = function(){
      braze.showContentCards(feed);
   }
</script>

toggleContentCards(parentNode, filterFunction) メソッドおよび showContentCards(parentNode, filterFunction) メソッドを使用する際、引数が指定されていない場合、すべてのContent Cardsがページ上の固定位置サイドバーに表示されます。引数が指定されている場合、フィードは指定された parentNode オプションに配置されます。

Content Cardsのトグルの詳細については、SDKリファレンスドキュメントを参照してください。

WebでのContent Cardsのテスト

ブラウザの開発者ツールを使用して、Content Cardsの統合をテストできます。

1. Content Cardsキャンペーンを作成し、テストユーザーをターゲットに設定します。
2. Web SDK統合が実装されているWebサイトにログインします。
3. ブラウザのコンソールを開きます。Chromeの場合、ページを右クリックし、検証 を選択してから Console タブを選択します。
4. コンソールで以下のコマンドを実行します。
   • window.braze.getCachedContentCards()
   • window.braze.toggleContentCards()

カードタイプとプロパティ

Content Cardsのデータモデルは Web SDKで利用でき、以下のContent Cardsタイプを提供します: ImageOnly、CaptionedImage、ClassicCard。各タイプは基本モデルのCardから共通プロパティを継承し、以下の追加プロパティを持ちます。

ヒント

Content Cardsのデータをログに記録するには、分析のログ記録を参照してください。

基本カードモデル

すべてのContent Cardsには以下の共通プロパティがあります:

画像のみ

ImageOnlyカードは、クリック可能なフルサイズの画像です。

キャプション付き画像

CaptionedImageカードは、説明テキストを伴うクリック可能なフルサイズの画像です。

クラシック

ClassicCardモデルは、テキストなしの画像、または画像付きのテキストを含むことができます。

画像フォーマット

Content Cardsの画像（GIFを含む）は、標準のHTML <img> タグを使用してレンダリングされます。GIFのサポートはユーザーのブラウザ機能に依存し、Web SDKの最小バージョンは必要ありません。すべてのモダンブラウザはGIF再生をネイティブにサポートしています。

コントロールグループ

デフォルトのContent Cardsフィードを使用している場合、インプレッションとクリックは自動的に追跡されます。

Content Cardsのカスタム統合を使用している場合、コントロールカードが表示されたであろうタイミングでインプレッションを記録する必要があります。この際、A/Bテストでインプレッションを記録する場合はコントロールカードを必ず処理するようにしてください。これらのカードは空白であり、ユーザーには表示されませんが、コントロールカード以外のカードとのパフォーマンスを比較するために、インプレッションを記録する必要があります。

Content CardがA/Bテストのコントロールグループに属しているかどうかを判定するには、card.isControlプロパティ（Web SDK v4.5.0以降）を確認するか、カードがControlCardインスタンスであるかどうか（card instanceof braze.ControlCard）を確認してください。

カードメソッド

デフォルトフィードメソッド

BrazeのデフォルトフィードのUIを使用してContent Cardsを表示する場合は、以下のメソッドを使用します。

カスタムフィードメソッド

独自のContent Cards UIを構築する場合は、以下のメソッドを使用します。

詳細については、SDKリファレンスドキュメントを参照してください。

ベストプラクティス

メソッドを正しい順序で呼び出す

カスタムフィードの場合、Content CardsはsubscribeToContentCardsUpdates()がopenSession()より前に呼び出された場合にのみ、セッション開始時にリフレッシュされます。Brazeのメソッドは次の順序で呼び出してください：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

import * as braze from "@braze/web-sdk";

// Step 1: Initialize the SDK
braze.initialize("YOUR-API-KEY", { baseUrl: "YOUR-SDK-ENDPOINT" });

// Step 2: Subscribe to card updates
braze.subscribeToContentCardsUpdates((updates) => {
  const cards = updates.cards;
  renderCards(cards);
});

// Step 3: Identify the user
braze.changeUser("USER_ID");

// Step 4: Start the session
braze.openSession();

キャッシュされたカードを使用してページ読み込み間でコンテンツを保持する

subscribeToContentCardsUpdates()は新しい更新がある場合（セッション開始時など）にのみコールバックを呼び出すため、ユーザーがセッション中にページを更新するとカスタムフィードからカードが消えることがあります。これを防ぐには、getCachedContentCards()を使用してローカルキャッシュからすぐにカードをレンダリングし、新しい更新のサブスクリプションと併用してください：

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
43
44
45
46
47
48
49
50
51
52
53

import * as braze from "@braze/web-sdk";

function renderCards(cards) {
  const container = document.getElementById("content-cards");
  container.textContent = "";
  const displayedCards = [];

  cards.forEach(card => {
    if (card instanceof braze.ClassicCard || card instanceof braze.CaptionedImage) {
      const cardElement = document.createElement("div");

      const h3 = document.createElement("h3");
      h3.textContent = card.title || "";
      cardElement.appendChild(h3);

      const p = document.createElement("p");
      p.textContent = card.description || "";
      cardElement.appendChild(p);

      if (card.imageUrl) {
        const img = document.createElement("img");
        img.src = card.imageUrl;
        img.alt = card.title || "";
        cardElement.appendChild(img);
      }

      if (card.url) {
        cardElement.addEventListener("click", () => {
          braze.logContentCardClick(card);
          braze.handleBrazeAction(card.url);
        });
      }

      container.appendChild(cardElement);
      displayedCards.push(card);
    }
  });

  if (displayedCards.length > 0) {
    braze.logContentCardImpressions(displayedCards);
  }
}

// Display cached cards immediately
const cached = braze.getCachedContentCards();
if (cached && cached.cards.length > 0) {
  renderCards(cached.cards);
}

// Subscribe to future updates
braze.subscribeToContentCardsUpdates((updates) => {
  renderCards(updates.cards);
});

カスタムフィードの分析をログに記録する

カスタムUIを使用している場合、インプレッション、クリック、非表示は自動的にトラッキングされません。各イベントを手動でログに記録する必要があります：

• インプレッション： カードがユーザーに表示されたときに、カードオブジェクトの配列を渡してlogContentCardImpressions([card1, card2, ...])を呼び出します。
• クリック： ユーザーがカードを操作したときにlogContentCardClick(card)を呼び出します。
• クリック時の動作： カードに設定されたクリック時のアクション（URLへのナビゲーションやカスタムイベントのログ記録など）を実行するためにhandleBrazeAction(card.url)を呼び出します。

警告

logContentCardClick()に渡す引数は、オリジナルのBraze Cardオブジェクトである必要があります。カードデータを変換または再構築した場合（シリアライズとデシリアライズなど）、クリックはログに記録されず、「card must be a Card object.」というエラーが表示されます。

Google Tag Managerの使用

Google Tag Managerは、Braze CDN（Web SDKのバージョン）をWebサイトのコードに直接挿入することで動作します。つまり、Content Cardsの実装を除き、Google Tag Managerを使用せずにSDKを統合した場合と同様に、すべてのSDKメソッドを利用できます。

Content Cardsの設定

• google tag manager
• 手動

1
2
3

<script>
   window.braze.showContentCards();
</script>

1
2
3

body .ab-feed {
    width: 800px;
}

テンプレートのアップグレード

Braze Web SDKの最新バージョンにアップグレードするには、Google Tag Managerダッシュボードで以下の3つのステップを実行します。

1. タグテンプレートの更新
   ワークスペース内のテンプレートページに移動します。更新が利用可能であることを示すアイコンが表示されます。
   
   
   
   そのアイコンをクリックし、変更内容を確認した後、Accept Updateをクリックします。
   
   
   
   
2. バージョン番号の更新
   タグテンプレートが更新されたら、Braze初期化タグを編集し、SDKバージョンを最新のmajor.minorバージョンに更新します。たとえば、最新バージョンが4.1.2の場合、4.1と入力します。SDKバージョンの一覧は変更履歴で確認できます。
   
   
   
   
3. QAと公開
   タグコンテナへの更新を公開する前に、Google Tag Managerのデバッグツールを使用して新しいSDKバージョンが正常に動作していることを確認します。

トラブルシューティング

タグデバッグの有効化

各Brazeタグテンプレートには、オプションのGTM Tag Debuggingチェックボックスがあり、Webページの JavaScript コンソールにデバッグメッセージをログ出力するために使用できます。

デバッグモードへの切り替え

Google Tag Manager統合のデバッグに役立つもう1つの方法は、Googleのプレビューモード機能を使用することです。

これにより、Webページのデータレイヤーから各トリガーされたBrazeタグに送信される値を特定でき、どのタグがトリガーされたか、またはトリガーされなかったかを確認できます。

カスタムイベントのタグシーケンスの確認

カスタムイベントやその他のアクションがBrazeにログ記録されない場合、よくある原因は、アクションタグ（Custom EventやPurchaseなど）がBraze Initializationタグの完了前に発火する競合です。これを修正するには、GTMでタグシーケンスを設定します。

1. 正しくログ記録されていないアクションタグを開きます。
2. Advanced Settings > Tag Sequencingで、A tag that fires before [this tag]を選択します。
3. セットアップタグとしてBraze Initializationタグを選択します。

これにより、アクションタグがBrazeにデータを送信する前に、SDKが完全に初期化されます。

詳細ログの有効化

トラブルシューティングのために詳細なログをキャプチャするには、Google Tag Manager統合で詳細ログを有効にできます。これらのログはブラウザの開発者ツールのConsoleタブに表示されます。

Google Tag Manager統合で、Braze初期化タグに移動し、Enable Web SDK Loggingを選択します。