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 CardsがA/Bテストのコントロールグループに属しているかどうかを判断するには、card.isControlプロパティ（Web SDK v4.5.0以降）を確認するか、カードがControlCardインスタンスであるかどうかを確認します（card instanceof braze.ControlCard）。

カードメソッド

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

Brazeのデフォルトフィードを使用して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)を呼び出します。
• クリック時の動作: handleBrazeAction(card.url)を呼び出して、カードに設定されたクリック時のアクション（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に記録されない場合、よくある原因は競合です。カスタムイベントや購入などのアクションタグが、Braze初期化タグの完了前に発火してしまうことがあります。これを修正するには、GTMでタグシーケンスを設定します。

1. 正しく記録されていないアクションタグを開きます。
2. 詳細設定 > タグシーケンスで、[このタグ]の前に発火するタグを選択します。
3. セットアップタグとしてBraze初期化タグを選択します。

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

詳細ログの有効化

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

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