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はsubscribeToContentCardsEvents()（または非推奨のsubscribeToContentCardsUpdates()）をopenSession()の前に呼び出した場合にのみ、セッション開始時に更新されます。Brazeのメソッドは次の順序で呼び出してください。

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

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
// - Available in version 7.0.0+
braze.subscribeToContentCardsEvents((event) => {
  switch (event.type) {
    case braze.ChannelEventType.CACHE_REPLAY:
    case braze.ChannelEventType.CACHE_LOAD:
    case braze.ChannelEventType.DATA_UPDATED:
      renderCards(event.cacheSnapshot.contentCards.cards);
      break;
  }
});

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();

Web SDK 7.0.0以降ではsubscribeToContentCardsEventsを使用してください。subscribeToContentCardsUpdatesは7.0.0で非推奨となった旧パターンです。

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

非推奨のsubscribeToContentCardsUpdates()メソッドは、新しい更新があった場合（セッション開始時など）にのみコールバックを呼び出すため、ユーザーがセッション中にページを更新すると、カスタムフィードからカードが消えることがありました。subscribeToContentCardsEvents()はこの問題を回避します。購読するとすぐにキャッシュされたカードを含むCACHE_REPLAYイベントが送信されるため、カスタムフィードはすべてのページ読み込み時にローカルキャッシュからレンダリングされます。

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
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

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);
  }
}

// - Available in version 7.0.0+
braze.subscribeToContentCardsEvents((event) => {
  switch (event.type) {
    case braze.ChannelEventType.CACHE_REPLAY:
      // Display cached cards immediately
      renderCards(event.cacheSnapshot.contentCards.cards);
      break;
    case braze.ChannelEventType.CACHE_LOAD:
    case braze.ChannelEventType.DATA_UPDATED:
      // Display cards after the cache reloads or a refresh finishes
      renderCards(event.cacheSnapshot.contentCards.cards);
      break;
  }
});

// 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);
});

Web SDK 7.0.0以降では、subscribeToContentCardsEventsがCACHE_REPLAYイベントですぐにキャッシュされたカードを配信するため、getCachedContentCards()を呼び出す必要はありません。subscribeToContentCardsUpdatesは7.0.0で非推奨となっています。

購読の外部でキャッシュされたカードが必要な場合は、getCachedContentCards()を呼び出してください。

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

カスタム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に記録されない場合、よくある原因は競合です。アクションタグ（カスタムイベントや購入など）がBraze初期化タグの完了前に発火してしまうことがあります。これを修正するには、GTMでタグシーケンスを設定します。

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

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

詳細ログの有効化

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

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