ウェブ用SDKの初期セットアップ

このリファレンス記事では、Braze Web SDK のインストール方法について説明します。Braze Web SDK を使えば、分析を収集し、豊富なアプリ内メッセージ、プッシュ、コンテンツカードメッセージを Web ユーザーに表示することができます。完全なテクニカルリファレンスについては、JavaScript Documentationを参照してください。

ステップ 1:Brazeライブラリをインストールする

Brazeライブラリは、以下のいずれかの方法でインストールできる。ウェブサイトがContent-Security-Policy を使用している場合、ライブラリをインストールする前に、コンテンツ・セキュリティ・ポリシー・ヘッダ・ガイドを参照のこと。

• package manager
• google tag manager
• braze cdn

1
2
3
npm install --save @braze/web-sdk
# or, using yarn:
# yarn add @braze/web-sdk

1
2
3
import * as braze from "@braze/web-sdk";
// or, using `require`
const braze = require("@braze/web-sdk");

ステップ2:SDK の初期化

Braze Web SDK を Web サイトに追加したら、Braze ダッシュボードの [設定] > [アプリ設定] にある API キーと SDK エンドポイント URL を使用してライブラリを初期化します。

braze.initialize() およびその他の JavaScript メソッドのオプションの完全なリストについては、JavaScript のドキュメントを参照してください。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// initialize the SDK
braze.initialize('YOUR-API-KEY-HERE', {
    baseUrl: "YOUR-SDK-ENDPOINT-HERE"
});

// optionally show all in-app messages without custom handling
braze.automaticallyShowInAppMessages();

// if you use Content Cards
braze.subscribeToContentCardsUpdates(function(cards){
    // cards have been updated
});

// optionally set the current user's external ID before starting a new session
// you can also call `changeUser` later in the session after the user logs in
if (isLoggedIn){
    braze.changeUser(userIdentifier);
}

// `openSession` should be called last - after `changeUser` and `automaticallyShowInAppMessages`
braze.openSession();

ステップ 3:プッシュ通知を設定する（オプション）

Braze Web SDK のプッシュ通知を設定するには、追加の設定が必要です。詳しい説明は、プッシュ通知（ウェブ版）を参照のこと。

ロギング

ロギングをすばやく有効にするには、?brazeLogging=true をパラメーターとして Web サイト URL に追加します。あるいは、基本ロギングまたはカスタム・ロギングを有効にすることもできる。

基本的なロギング

• 初期化前
• 初期化後

1
enableLogging: true

1
2
3
4
5
braze.initialize('API-KEY', {
    baseUrl: 'API-ENDPOINT',
    enableLogging: true
});
braze.openSession();

1
2
3
4
5
6
braze.initialize('API-KEY', {
    baseUrl: 'API-ENDPOINT',
});
braze.openSession();
...
braze.toggleLogging();

カスタムロギング

setLogger を使用して、カスタムデバッグメッセージを javascript コンソールに記録します。基本ログとは異なり、これらのログはユーザーには見えない。

1
setLogger(loggerFunction: (message: STRING) => void): void

STRING を1つの文字列パラメーターとしてメッセージに置き換えます。メソッドは次のようになるはずです。

1
2
3
4
5
braze.initialize('API-KEY');
braze.setLogger(function(message) {
    console.log("Braze Custom Logger: " + message);
});
braze.openSession();

SDKをアップグレードする

Braze Web SDKを当社のコンテンツデリバリーネットワーク、例えばhttps://js.appboycdn.com/web-sdk/a.a/braze.min.js （当社のデフォルトの統合手順で推奨されている）から参照すると、ユーザーがサイトを更新したときに、マイナーアップデート（バグフィックスと下位互換機能、上記の例ではバージョンa.a.a ～a.a.z ）を自動的に受け取ることができる。

ただし、当社が大きな変更をリリースする場合は、Braze Web SDK を手動でアップグレードして、統合に重大な変更の影響がないようにする必要があります。さらに、当社のSDKをダウンロードして自分でホスティングする場合、バージョン・アップデートを自動的に受け取ることはできないので、最新の機能やバグ修正を受け取るには手動でアップグレードする必要がある。

RSS Reader または任意のサービスを使用して、リリースフィードに従って最新のリリースを取得できます。また、Web SDK のリリース履歴の詳細については、変更ログを参照してください。Braze Web SDKをアップグレードする：

• バージョン番号 https://js.appboycdn.com/web-sdk/[OLD VERSION NUMBER]/braze.min.js を変更するか、パッケージマネージャーの依存関係で、Braze ライブラリのバージョンを更新します。
• Web プッシュが統合されている場合は、サイトのサービスワーカーファイルを更新します。デフォルトでは、このファイルはサイトのルートディレクトリの/service-worker.js にありますが、統合によっては場所がカスタマイズされている場合があります。サービスワーカーファイルをホストするには、ルートディレクトリにアクセスしなければならない。

これら2つのファイルを適切に機能させるには、相互に連携して更新する必要があります。

別の統合方法

サーバーサイド・レンダリング・フレームワーク

Next.js のようなサーバーサイド・レンダリング・フレームワークを使用している場合、SDKはブラウザ環境で実行されることを想定しているため、エラーが発生する可能性がある。これらの問題は、SDKを動的にインポートすることで解決できる。

必要な SDK の部分を別のファイルにエクスポートし、そのファイルをコンポーネントに動的にインポートすることで、ツリーシェイクの利点を維持できます。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// MyComponent/braze-exports.js
// export the parts of the SDK you need here
export { initialize, openSession } from "@braze/web-sdk";

// MyComponent/MyComponent.js
// import the functions you need from the braze exports file
useEffect(() => {
    import("./braze-exports.js").then(({ initialize, openSession }) => {
        initialize("YOUR-API-KEY-HERE", {
            baseUrl: "YOUR-SDK-ENDPOINT",
            enableLogging: true,
        });
        openSession();
    });
}, []);

あるいは、アプリのバンドルにwebpackを使用している場合、そのマジックコメントを利用して、必要なSDKの部分だけを動的にインポートすることもできる。

1
2
3
4
5
6
7
8
9
10
11
12
13
// MyComponent.js
useEffect(() => {
    import(
        /* webpackExports: ["initialize", "openSession"] */
        "@braze/web-sdk"
    ).then(({ initialize, openSession }) => {
        initialize("YOUR-API-KEY-HERE", {
            baseUrl: "YOUR-SDK-ENDPOINT",
            enableLogging: true,
        });
        openSession();
    });
}, []);

Vite でのサポート

Viteを使用していて、循環依存関係やUncaught TypeError: Class extends value undefined is not a constructor or null に関する警告が表示される場合は、Braze SDKを依存関係の発見から除外する必要があるかもしれない：

1
2
3
optimizeDeps: {
    exclude: ['@braze/web-sdk']
},

Electron でのサポート

Electron は公式には Web プッシュ通知をサポートしていません (参照： この GitHub issue)。Brazeがテストしていないオープンソースの回避策を試すこともできる。

AMDモジュール・ローダー

RequireJS または他の AMD モジュールローダーを使用する場合は、ライブラリのコピーをセルフホスティングし、他のリソースと同様に参照することをお勧めします。

1
2
3
4
5
require(['path/to/braze.min.js'], function(braze) {
  braze.initialize('YOUR-API-KEY-HERE', { baseUrl: 'YOUR-SDK-ENDPOINT' });
  braze.automaticallyShowInAppMessages();
  braze.openSession();
});

代替案 AMDを設置しない

サイトで RequireJS または別の AMD モジュールローダーを使用しているが、上記の他のオプションのいずれかを使用して Braze Web SDK をロードしたい場合は、AMD サポートを含まないバージョンのライブラリをロードできます。このバージョンのライブラリーは、以下のCDNの場所からロードできる：

Tealium iQ

Tealium iQは、基本的なターンキー Braze 統合を提供します。統合を構成するには、Tealium Tag Management インターフェイスで Braze を検索し、ダッシュボードから Web SDK API キーを指定します。

詳細または Tealium 構成サポートに関する詳細については、統合ドキュメントを確認するか、Tealium アカウントマネージャーにお問い合わせください。

その他のタグ・マネージャー

Brazeは、カスタムHTMLタグの中で当社の統合指示に従うことにより、他のタグ管理ソリューションと互換性を持つこともできる。これらのソリューションの評価についてサポートが必要な場合は、Brazeの担当者に連絡すること。

Jestフレームワークのトラブルシューティング

Jestを使用している場合、SyntaxError: Unexpected token 'export' のようなエラーが表示されることがある。これを修正するには、Braze SDK を無視するように package.json の設定を調整します。

1
2
3
4
5
"jest": {
  "transformIgnorePatterns": [
    "/node_modules/(?!@braze)"
  ]
}