Singular WebサイトSDK：ネイティブ統合

フォローする
Avatar
Jared Ornstead
Updated

 

Singular Website SDKは企業向け機能です。この機能のご利用をご希望の場合は、カスタマーサクセスマネージャーまでお問い合わせください。

Singular Website SDKを使用すると、ウェブサイトのアクティビティをマーケティングのタッチポイントに関連付けたり、ウェブサイト内のユーザーイベントを追跡したりすることができます。また、Singularのクロスデバイスアトリビューションソリューションの重要なコンポーネントでもあり、ユーザージャーニーを分析し、クロスプラットフォームのLTVとROASを計算することができます。

詳しくはクロスデバイスアトリビューションFAQと ウェブアトリビューションFAQをご覧ください。

ここで説明するネイティブJavaScriptバージョンに加え、Singular Website SDKはGoogle Tag Manager Templateとしてもご利用いただけます。

ブラウザの互換性

Chrome: 15以上 エッジ：15以上 Internet Explorer10+
サファリ5.1+ ファイアフォックス6+ オペラ：15以上

SDKスクリプトをサイトに追加する

お客様のウェブサイトまたはウェブアプリにSDKを設定するには、以下のいずれかの方法をご利用ください。

SingularのCDN上のスクリプトへのリンク

この方法では、SDKのJavaScriptコードをSingularのCDNでホストします。

追跡したい各ページの<head>タグ内に以下のコードを追加します：

<head>
      <!-- 最新のSDKバージョンを使用する   -->
      <script src="https://web-sdk-cdn.singular.net/singular-sdk/latest/singular-sdk.js">
      </script>
</head>

注：上記のコードは最新バージョンのSDKにリンクしています。特定のバージョンのSDKを使用したい場合は、代わりに以下のコードを使用してください：

<head>
      <!-- 固定SDKバージョンの使用   -->
      <script src="https://web-sdk-cdn.singular.net/singular-sdk/1.4.2/singular-sdk.js">
      </script>
</head>

NPMを使用したセットアップ

  1. プロジェクトのルート・ディレクトリでnpm i singular-sdkを実行するか、"singular-sdk" を追加します："^1.4.1 " をpackage.jsonファイルの dependencies セクションに追加し、npm install を実行します。
  2. SDKを使用したいスクリプトに以下のコードを追加します。
import {singularSdk, SingularConfig} from "singular-sdk";

SDKの初期化

SDKの初期化コードは、ページがロードされるたびに呼び出される必要があります。 これはすべてのSingularアトリビューション機能の前提条件であり、以下のような機能もあります：

  • ユーザーが新しい広告データでサイトに入ったとき、またはセッションタイムアウトが過ぎたときに、新しいユーザーセッションを作成します。
  • 新しい「ページ訪問」イベントをSingularに送信します。

ページ訪問イベントとユーザーセッションは、ユーザーのリテンションを計算し、リエンゲージメントアトリビューションを可能にするために使用されます。

1.SingularConfig オブジェクトの構築

SDKを初期化する前に、SingularConfigオブジェクトを作成する必要があります。このオブジェクトには以下が含まれます：

  • SDKキーとSDKシークレット：これらを見つけるには、Singularアカウントにログインし、"Developer Tools > SDK Integration > SDK Keys "にアクセスしてください。
  • あなたのプロダクトID：お客様のウェブサイトの名前です。例えば、"com.example "のように、メインウェブドメインの逆DNS表記を使用することをお勧めします。これはSingularプラットフォーム全体でお客様のウェブサイトを識別するために使用されます。この値は、SingularプラットフォームのAppsページのApp bundleIDとも一致する必要があります。
  • オプションとして、設定したいSDKの環境設定（詳細はこちらをお読みください）を指定します。

基本的なSingularConfigオブジェクトを作成するにはこのコードを使います：

const config = new SingularConfig(sdkKey, sdkSecret, productId);

しかし、Singularが提供する様々な機能を有効にするための設定を追加したいと思うでしょう。

設定を追加するには、SingularConfigオブジェクトの".with "メソッドを使います。例えば

  // ユーザーIDをSingularに渡すようにSDKを設定する。
  const config = new SingularConfig(sdkKey, sdkSecret, productId)
      .withCustomUserId(userId);

SingularConfig メソッドリファレンス

利用可能なすべての ".with" メソッドを以下に示します。

メソッド 説明 詳細
.withCustomUserId(customId) ユーザーIDをSingularに送信する ユーザーIDの設定
.withProductName(productName) 商品の表示名（オプション  
.withLogLevel(logLevel) ロギング・レベルの設定： 0 - なし（デフォルト）; 1 - 警告; 2 - 情報; 3 - デバッグ。  
.withSessionTimeoutInMinutes(timeout) セッションタイムアウトを分単位で設定する（デフォルト：30分）

 
.withAutoPersistentSingularDeviceId (domain) 自動クロスサブドメイントラッキングを有効にする クッキーを使った自動永続化

.withPersistentSingularDeviceId (singularDeviceId)

 手動でのクロスサブドメイントラッキングを有効にする 特異デバイスIDを手動で設定
.withInitFinishedCallback(callback) SDK初期化完了時にコールバックを呼び出す 初期化完了時にコールバック関数を呼び出す

2.Singularの初期化

SingularConfigオブジェクトを作成したら、initメソッドでconfigオブジェクトを渡してSingularを初期化します。

init メソッドはコードのどの時点でも呼び出せますが、イベントが報告される前に呼び出される必要があります。追跡したい各ページのロード中に init を呼び出すことをお勧めします。

init メソッド
説明 SingularConfigオブジェクトに設定された設定オプションでSDKを初期化します。
シグネチャ init(config)
使用例 
  function initSingular() {
      const config = new SingularConfig(sdkKey, 
        sdkSecret, productId);
      singularSdk.init(config);
  }

重要：単一ページアプリケーション（SPA）の場合、異なるページにルーティングするたびに singularSdk.pageVisit() を呼び出します。singularSdk.initはすでにページ訪問を報告しているため、最初にロードされたページではsingularSdk.pageVisit()を呼び出さないでください。

初期化完了時のコールバック関数の呼び出し

初期化が完了したら呼び出されるコールバック関数を設定するには、SingularConfigオブジェクトで .withInitFinishedCallback(callback)を使用します。

withInitFinishedCallback メソッド
説明 初期化プロセスが終了したときに呼び出されるコールバックを設定します。
シグネチャ withInitFinishedCallback(callback)
使用例 
  function initSingular() {      
    const config = new SingularConfig(sdkKey, sdkSecret, productId)
      .withInitFinishedCallback(initParams=> {
        // このコールバックは、initメソッドが終了するときに呼び出される。
  
        // シングル・デバイスIDはこちらで取得できます。
        const singularDeviceId = initParams.singularDeviceId;
      });
  singularSdk.init(config);
  }

ユーザーIDをSingularに送信する（オプション）

Singular SDKのメソッドを使用して、内部ユーザーIDをSingularに送信することができます。

注意： Singularのクロスデバイスソリューションをご利用の場合は、すべてのプラットフォームでユーザーIDを収集する必要があります。

  • ユーザーIDはどのような識別子でもかまいませんが、PII（個人を特定できる情報）を公開するべきではありません。 例えば、ユーザーのメールアドレス、ユーザー名、電話番号は使用しないでください。Singularは、お客様のファーストパーティデータにのみユニークなハッシュ値を使用することを推奨します。
  • Singularに渡すユーザーIDは、すべてのプラットフォーム（ウェブ/モバイル/PC/コンソール/オフライン）で同じ内部ユーザーIDを使用する必要があります。
  • Singularはユーザーレベルのエクスポート、ETL、内部BIポストバック（設定されている場合）にユーザーIDを含めます。ユーザーIDはファーストパーティデータであり、Singularが他者と共有することはありません。
  • ユーザーIDの値は、Singular SDKメソッドで設定されると、logout() メソッドで設定が解除されるまで、またはブラウザのローカルストレージが削除されるまで保持されます。ウェブサイトを閉じたり更新しても、ユーザーIDは解除されません。
  • プライベート/インコグニートモードでは、ブラウザが閉じられるとローカルストレージが自動的に削除されるため、SDKはユーザーIDを永続化できません。

ユーザーIDを設定するには、login() メソッドを使用します。設定を解除するには（ユーザーがアカウントを「ログアウト」した場合など）、logout() メソッドを呼び出します。

注：複数のユーザが1つのデバイスを使用する場合、ログインとログアウトのたびにユーザIDを設定・解除するログアウトフローを実装することを推奨します。

ウェブサイト上でSingular SDKが初期化されたときにすでにユーザーIDがわかっている場合は、設定オブジェクトにユーザーIDを設定します。こうすることで、Singularは最初のセッションからユーザーIDを持つことができます。しかし、ユーザーIDは通常、ユーザーが登録するかログインを実行するまで使用できません。その場合は、登録フローが完了してからlogin() を呼び出します。

SingularSDK login() メソッド
説明 ユーザーIDをSingularに送信します。
シグネチャ login(customUserId)
使用例 
singularSdk.login("custom_user_id");
SingularSDK logout() メソッド
説明 Singular に送信されたユーザー ID の設定を解除します。
シグネチャ ログアウト()
使用例 
singularSdk.logout();

オプションカスタムユーザーID デバイスマッピング

重要：この高度なエンタープライズ機能は、例外的な場合にのみ使用できます。実装する前にSingularのソリューションエンジニアにご相談ください。

Singularはサーバー間の統合により、追加のモバイルイベント追跡データを受け取ることができます。この機能を利用するには、ユーザーIDをSingularのモバイルデバイス追跡識別子にマッピングする必要があります。

注意：Singular SDKを初期化した後、またはユーザーIDを取得した後、できるだけ早くこのメソッドを呼び出してください。

SingularSDK setDeviceCustomUserId メソッド
説明 ログイン時と同じカスタムユーザーIDを設定し、Singularのトラッキング識別子にマッピングします。
シグネチャ singularSdk.setDeviceCustomUserId(userId)
使用例 
singularSdk.setDeviceCustomUserId("customUserId");

オプションイベントと収益の追跡

イベントのトラッキング（非収益）

Singularはサイト内のユーザーイベントに関するデータを収集し、キャンペーンのパフォーマンス分析やKPIの測定に役立てることができます。例えば、ユーザーのログイン、登録、チュートリアルの完了などのデータを収集したい場合があります。

イベントをSingularに送信するには、eventメソッドを使用します。

注意

  • サードパーティのパートナーや分析ソリューションとの互換性を保証するために、イベント名と属性を英語で渡すことを強くお勧めします。
  • イベント名は32 ASCII文字までに制限されています。非ASCII文字の文字列は、UTF-8に変換された後、32バイト以下にする必要があります。
  • 属性と値は500 ASCII文字に制限されています。
イベント メソッド
説明 追加情報の有無にかかわらず、ユーザーイベントをSingularに報告します。
シグネチャ

singularSdk.event(eventName, args)

注: 'args' は、キーと値のペアを持つJavaScriptオブジェクトです。追加の引数を渡したくない場合は、イベント名のみを指定してeventメソッドを呼び出します。
使用例 
  // 引数なしで Registration_Completed イベントを送信します。
  singularSdk.event("Registration_Completed");

  // 追加プロパティを持つ "Registration_Completed "という名前のイベントを送信する。
  singularSdk.event("Registration_Completed",
  {key1: 'value1',
  key2: 'value2'});

収益のトラッキング

Singularはウェブサイトを通じて得た収益に関するデータを収集し、キャンペーンのパフォーマンスやROIの分析に役立てることができます。Singularはレポート、ログエクスポート、ポストバックでデータを利用できるようにします。

イベントのレポートには収益メソッドを使用します。収益ではカスタムイベント名を渡すことができ、Singularのレポートで収益を収益イベントの種類別に分けて表示することができます。

注意事項 異なる通貨で報告された収益は、Singularアカウントで設定された組織の優先通貨に自動変換されます。

収益 方法
説明 収益イベントをオプションの追加情報と共にSingularに送信します。
シグネチャ

singularSdk.revenue(eventName, currency, amount, args)

注意

  • currencyは、"USD"、"EUR"、"INR "などの3文字のISO 4217通貨コードとして渡します。
  • 金額値は、10進数値として渡すことができます。
使用例 
  // 収益イベントをSingularに送る
  singularSdk.revenue("Item_Purchased","USD", 5.50);

  // 追加引数でSingularに収益イベントを送る
  singularSdk.revenue("Item_Purchased","USD", 5.50,
  {key1: 'value1',
   key2: 'value2');

オプションクロスサブドメイントラッキング

デフォルトでは、SingularウェブサイトSDKはSingularデバイスIDを生成し、ブラウザストレージを使用して永続化します。このストレージはサブドメイン間で共有できないため、SDKは結局サブドメインごとに新しいIDを生成します。

サブドメイン間でSingular Device IDを永続化したい場合は、以下のいずれかの方法をご利用ください：

方法A：クッキーを使った自動永続化

Singular SDKにカスタムファーストパーティークッキーを使用してSingular Device IDを永続化させることができます。以下の方法を使用し、追跡したいメインドメインを設定します。

withAutoPersistentSingularDeviceId メソッド
説明 Singular Device IDを自動永続化するためのメインドメインを含む設定オプションでSDKを初期化します。
シグネチャ withAutoPersistentSingularDeviceId(domain)
使用例 
  function initSingular() {
    const config = new SingularConfig(sdkKey, sdkSecret, productId)
      .withAutoPersistentSingularDeviceId(“example.com”);
    singularSdk.init(config);
  }

方法B（詳細）：特異デバイスIDを手動で設定する

Singular SDKにデバイスIDを自動的に保持させたくない場合は、例えばトップレベルドメインCookieやサーバーサイドCookieを使って、ドメイン間でIDを手動で保持することができます。値はSingularが以前に生成したIDで、有効なuuid4形式でなければなりません。

注：Singular Device IDは、initメソッドを呼び出した後、またはInitFinishedCallbackを使用して、singularSdk.getSingularDeviceId()を使用して読み取ることができます。

withPersistentSingularDeviceId メソッド

説明

永続化したいシンギュラー・デバイス ID を含む構成オプションで SDK を初期化します。
シグネチャ withPersistentSingularDeviceId(singularDeviceId)
使用例 
  function initSingular() {
    const config = new SingularConfig(sdkKey, sdkSecret, productId)
      .withPersistentSingularDeviceId(singularDeviceId);
    singularSdk.init(config);
  }

オプション：マッチIDの取得

重要： これは高度な機能です。実装する前にSingularのソリューションエンジニアにご相談ください。

Singularは、ユーザーごとに決定論的に一意のマッチIDに基づいて、PCおよびコンソールプラットフォームからサーバーへのインストールを識別することができます。この機能を利用するには、初期化後にSingularのウェブSDKからマッチIDを取得してください。

getMatchID メソッド
説明 このウェブセッションの一意のマッチIDを取得します。
署名 singularSdk.getMatchID()
使用例 
  // 他のプラットフォームの最初のセッションに含まれるユーザーマッチIDを取得する。
  singularSdk.getMatchID()