Web用の初期SDKセットアップ

このリファレンス記事では、Braze Web SDK のインストール方法について説明します。Braze Web SDKを使用すると、分析を収集し、リッチなアプリ内メッセージ、プッシュ、およびコンテンツカードメッセージをWebユーザーに表示できます。完全な技術リファレンスについては、JavaScriptドキュメントをご覧ください。

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

次の方法のいずれかを使用して、Brazeライブラリーをインストールできます。あなたのWeb サイトが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のプッシュ通知を設定するには、追加の設定が必要です。完全なウォークスルーについては、Webのプッシュ通知を参照してください。

ログイン

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

基本的なロギング

• before initialization
• after initialization

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
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リーダーやお好みのサービスでリリースフィードをフォローすることで、最新のリリース情報を常に把握できます。また、Web SDKのリリース履歴の全容については、変更履歴をご覧ください。Braze Web SDKをアップグレードするには:

• {更新} {Braze} {ライブラリー} バージョンを変更することによって https://js.appboycdn.com/web-sdk/[OLD VERSION NUMBER]/braze.min.js のバージョン番号を変更するか、パッケージ{マネージャー}の依存関係で変更します。
• 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を使用している場合、マジックコメントを利用して、必要な部分だけを動的にインポートすることができます。

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}

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

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

エレクトロンのサポート

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

代替案 No AMD インストール

あなたのサイトがRequireJSや他のAMDモジュールローダーを使用しているが、上記の他のオプションのいずれかを通じてBraze Web SDKを読み込みたい場合、AMDサポートを含まないバージョンのライブラリーを読み込むことができます。このバージョンのライブラリーは、次のCDNの場所からロードできます:

Tealium iQ

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

詳細や詳細なTealium構成サポートについては、統合ドキュメントをご覧いただくか、Tealiumのアカウントマネージャーにお問い合わせください。

他のタグマネージャー

Brazeは、カスタムHTMLタグ内の統合手順に従うことで、他のタグ管理ソリューションとも互換性がある場合があります。これらのソリューションの評価に関して支援が必要な場合は、Brazeの担当者に連絡してください。

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

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

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