Singular SDKはCordovaのプラグインとしてご利用いただけます。以下の説明 に、SingularをCordovaアプリに統合する方法を示します。

前提条件

• この記事は、あなたが機能的なCordovaアプリを持っていることを前提としています。
• SDKを初期化するには、Singular SDK KeyとSDK Secretが必要です。これらはSingularプラットフォームの "Developer Tools > SDK Integration > SDK Keys "から入手できます。

Singularプラグインの追加

SingularプラグインをCordovaプロジェクトに追加するには、以下を実行します：

cordova plugin add singular_cordova_sdk

Ionic

Ionicを使用している場合：

1. Singular SDKプラグインをインストールします：

   $ ionic cordova plugin add singular_cordova_sdk

2. メインのtsファイルで、window変数を宣言します：

   declare var cordova;

3. これで、Cordovaから直接Singularプラグインを使用できるようになります：

   import {Component} from '@angular/core';
     import {Platform} from '@ionic/angular';
     declare var cordova;
     ...
     
     export class HomePage {
     constructor(public platform: Platform) {
     this.platform.ready().then(() => {
     
         // ここに Singular SDK を初期化するコードを追加します
     
     }); 
     }}

SDKの初期化（必須）

Singular SDKの初期化コードは、アプリを開くたびに呼び出す必要があります。これはすべてのSingular属性機能の前提条件です。また、新しいユーザーセッションをSingularに送信します（セッションはユーザーのリテンションを計算するために使用されます）。

Singular SDKを初期化します：

1. SingularConfig オブジェクトを作成します。このオブジェクトにはSingular SDK KeyとSecretが含まれます。
2. アプリでディープリンクやSKAdNetworkをサポートしたい場合は、オプションの設定を行います（下記の「ディープリンクサポートの追加」と「SKAdNetworkサポートの追加」を参照してください）。
3. METAインストール・リファラー帰属のサポート

   Meta Install Referrer」アトリビューションを有効にするために必要なSDK設定です：

   1. Singular構成オブジェクトにFacebookアプリIDを入力してください。
      

      // META インストールリファラーを有効にするには
      singularConfig.withFacebookAppId("ここに Facebook アプリ ID を入力してください");

   アプリのFacebookアプリIDはどこで確認できますか？
4. SingularConfigオブジェクトを使用してSDKを初期化します。

コード例（オプション設定はコメントアウトされています）：

// 構成オブジェクトを作成する
  var singularConfig = new
  cordova.plugins.SingularCordovaSdk.SingularConfig("<SDK KEY>", "<SDK SECRET>");
  
  /*
  // オプション: ディープリンクを有効にします (追加のセットアップ手順が必要です。ガイドを参照)
  var linkHandler = function(data){
  var deeplink = data.deeplink;
  var passthrough = data.passthrough;
  var isDeferred = data.isDeferred;
  // ここにリンク処理ロジックを追加します
  }
  singularConfig.withSingularLink(linkHandler);
  */
  
  /*
  // META インストールリファラーを有効にするには
  singularConfig.withFacebookAppId("ここに Facebook アプリ ID を入力してください");
  */
  
  /*
  // オプション: SKAdNetwork を有効にします (管理モードの場合、その他のオプションについてはガイドを参照してください)
  singularConfig.withSkAdNetworkEnabled(true);
  */
  
  // 単数形の初期化
  cordova.plugins.SingularCordovaSdk.init(singularConfig);

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

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

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

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

アプリを開いたときにユーザーIDがすでに分かっている場合は、Singular SDKを初期化する前にsetCustomUserId 。こうすることで、Singularは最初のセッションからユーザーIDを持つことができます。しかし、ユーザーIDは通常、ユーザーが登録するかログインを実行するまで利用できません。その場合は、登録フローが完了した後にsetCustomUserId 。

SingularCordovaSdk.setCustomUserId('CustomUserId');

SingularCordovaSdk.unsetCustomUserId();

SingularCordovaSdk.setDeviceCustomUserId('CustomUserId');

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

SDKを初期化することで）ユーザーセッションをSingularに送信するだけでなく、ユーザーイベントを送信することもできます。アプリ内イベントのデータは、Singularがユーザー獲得キャンペーンのパフォーマンスを分析し、KPIを測定するのに役立ちます。

例えば、ゲームアプリでユーザーのログイン、登録、チュートリアルの完了、レベルアップなどのデータを収集したい場合があります。

Singularにイベントを送信するには、eventWithArgs メソッドを使います。イベントに名前を付け、追跡したい属性を追加します。

// 例: イベント属性を使用して「View Product」というイベントをレポートします。
  cordova.plugins.SingularCordovaSdk.eventWithArgs(
    'ViewProduct', // イベント名
    {
      // イベント属性
      productID:"123",
      productCategory:"Outerwear"
    }
  )

収益のトラッキング

アプリ内課金による収益をSingularにトラッキングさせるには、IAPイベントをSingularに報告します。

eventWithArgsメソッドを使い、IAPオブジェクトをイベント属性として渡すことをお勧めします。SingularはIAPオブジェクトを使って購入を検証し、不正購入を検出することで、収益指標を歪めないようにします（アプリ内購入の検証に関するFAQを参照）。

https://github.com/j3k0/cordova-plugin-purchaseライブラリを使用している場合は、以下のコードを使用できます：

store.when('product123 verified', onProductVerified);
  product.verify();
  
  function onProductVerified(product){
    const iap = new cordova.plugins.SingularCordovaSdk.SingularIAP(product);
    cordova.plugins.SingularCordovaSdk.eventWithArgs('IAP_EVENT', iap)
  }

cordova.plugins.SingularCordovaSdk.customRevenue(
    customEventName, // 例 "purchase"
    currencyCode, // 例 "USD"
    purchaseAmount //  例 3.2
  );

ハイブリッドイベントトラッキング（上級者向け）

Singularでは、アプリに統合されたSingular SDKを通してすべてのイベントと収益を送信することを推奨しています。ただし、Singularは他のソースからイベントと収益を収集することもできます。

Singular SDKから送信されないイベントは、Singularのサーバー間イベントドキュメンテーション要件に準拠し、イベントの属性を正しく設定するために一致するデバイス識別子を提供する必要があります。

ハイブリッドイベント追跡ガイド

広告収益アトリビューションのトラッキング

ディープリンクサポートの追加

ディープリンクとは、ユーザーの携帯電話でアプリを開き、アプリのメインウィジェットだけでなく、特定のページやユーザーエクスペリエンスに直接ユーザーを送るリンクです。

ディープリンクは通常、リターゲティングキャンペーンで使用され、すでに携帯電話にアプリを持っているが、しばらくアプリを使用していないユーザーを対象としています。

SingularはSingular Linksを通してディープリンクをサポートしています（Singular Links FAQをご覧ください）。

アプリでSingular Linksを使用するには

1. Singular Links Prerequisitesの指示に従ってください。

2. Androidの場合は、このコードをメインアクティビティに追加してください：

   import singular_cordova_sdk.SingularCordovaSdk;
     
     @Override
     public void onNewIntent(Intent intent) {
       SingularCordovaSdk.handleNewIntent(intent);
     }

   iOSの場合は、このコードをAppDelegateに追加してください：

   #import "SingularCordovaSdk.h"
     
       - (BOOL)application:(UIApplication*)application
       didFinishLaunchingWithOptions:(NSDictionary*)launchOptions
       {
          self.viewController = [[MainViewController alloc] init];
          [SingularCordovaSdk setLaunchOptions: launchOptions];
          return [super
       application:application didFinishLaunchingWithOptions:launchOptions];
       }
     
       - (BOOL)application:(UIApplication *)application
       continueUserActivity:(NSUserActivity *)userActivity
       restorationHandler:(void (^)(NSArray<id> * _Nullable))restorationHandler{
        [SingularCordovaSdk startSessionWithUserActivity:userActivity];
        return
       YES;
       }

3. コード内でSingular SDKを初期化する前に、Singular configオブジェクトに.withSingularLinkを 追加し、リンクハンドラ関数を指定してください：

   var singularConfig = new
       cordova.plugins.SingularCordovaSdk.SingularConfig("<SDK KEY>", "<SDK SECRET>");
     
     var linkHandler = function(data){
       var deeplink = data.deeplink;
       var passthrough = data.passthrough;
       var isDeferred = data.isDeferred;
       // ここにリンク処理ロジックを追加します
     }
     
     singularConfig.withSingularLink(linkHandler);
     
     cordova.plugins.SingularCordovaSdk.init(singularConfig);

SKAdNetworkサポートの追加

SingularプラグインはSKAdNetworkフレームワークをサポートしています。以下の設定オプションを使って、アプリのSKAdNetworkトラッキングを有効にすることができます。

マネージドモード（推奨）

マネージドモードでは、Singularプラットフォームで設定できるお好みのコンバージョンモデルに基づいて、Singularが自動的にSKAdNetworkのコンバージョン値を管理します。

詳しくは、 Singularのコンバージョンバリュー管理についてと SKAdNetworkモデル設定FAQをご覧ください。 SingularでSKAdNetworkを使用するためのステップバイステップガイドは、 SKAdNetworkの始め方をご覧ください。

マネージドモードで SKAdNetwork を有効にするには、以下のコードを使用してください：

var singularConfig = new
    cordova.plugins.SingularCordovaSdk.SingularConfig("<SDK KEY>", "<SDK SECRET>");
  
  // SKAdNetwork を有効にする (デフォルトでは管理モード)
  singularConfig.withSkAdNetworkEnabled(true);
  
  cordova.plugins.SingularCordovaSdk.init(singularConfig);

マニュアルモード

SKAdNetworkのコンバージョン値を管理するための独自の戦略とツールをすでにお持ちの場合は、SKAdNetworkをマニュアルモードで使用することができます。

マニュアルモードでSKAdNetworkを有効にするには、以下のコードを使用します：

var singularConfig = new
    cordova.plugins.SingularCordovaSdk.SingularConfig("<SDK KEY>", "<SDK SECRET>");
  
  // SKAdネットワークを有効にする
  singularConfig.withSkAdNetworkEnabled(true);
  
  // SKAdNetwork 手動モードを選択します
  singularConfig.withManualSkanConversionManagement();
  
  // オプション: コンバージョン値の変更を追跡するハンドラーを定義します。
  var conversionHandler = function(updatedConversionValue){
    // updatedConversionValue を使って何かを行う
  }
  
  singularConfig.withConversionValueUpdatedHandler(conversionHandler);
  
  // Singular SDK を初期化する
  cordova.plugins.SingularCordovaSdk.init(singularConfig);

変換値を更新するには、以下のコードを使用します：

cordova.plugins.SingularCordovaSdk.skanUpdateConversionValue(
    newConversionValue,
    function(isSuccess){
      // isSuccess == 更新が成功した場合は true
    }
  )

現在の変換値を取得するには、以下のコードを使用します：

cordova.plugins.SingularCordovaSdk.skanGetConversionValue(
    function(conversionValue){
      // コンバージョン値を使って何かをする
    }
  )

その他のオプション

アンインストールのトラッキング

Singularにアプリのアンインストールを追跡させるには、以下のコードを使用してAPNS/FCMトークンをSingularに送信します：

Android

cordova.plugins.SingularCordovaSdk.setUninstallToken(fcmToken)

iOS

cordova.plugins.SingularCordovaSdk.setUninstallToken(apnsToken)

短いリファラーリンクの作成

ショートリンクを使うと、長いパラメータだらけのSingularリンクを、共有に便利な短くて安全なリンクに変換できます。

通常、短いリンクを動的に作成して、アプリのユーザーが友達と共有してアプリの使用を招待できるようにします。

ショートリンクを作成するには

• アプリのダウンロードにつながるシンギュラーリンク（ シンギュラーリンクのFAQを参照）。
• リンクに動的に追加したいパラメータ（オプションの一覧は トラッキングリンクパラメータをご覧ください）。
• リンクを共有したユーザーをさかのぼって新しいアプリのインストールを追跡できるようにしたい場合は、参照元ユーザーの名前とID。

ショートリンクを作成するには、以下のコードを使用します：

cordova.plugins.SingularCordovaSdk.createReferrerShortLink(
      longLinkURL, 
      referrerName,
      referrerID,
      {
          // ショートリンクに追加するトラッキングリンクパラメータの例 "channel":"sms"
          param1: value1,
          param2: value2,
          ...
      },
      {
          onSuccess: function (shortLinkURL) {
          // shortLinkURL を使って何かをする
          },
          onError: function (error) {
          // ハンドルエラー
          }
      }
  )

データプライバシー法の遵守

Singularは、GDPRやCCPA（カリフォルニア州消費者プライバシー法）のような消費者プライバシー法を遵守している可能性のあるパートナーと協力できるように、プライバシー保護機能を提供しています。 これらのパートナーは、エンドユーザーが個人情報の共有に同意した場合に通知されることを望んでいます。

ユーザーに情報共有の同意を求める方法を実装している場合は、limitDataSharingメソッドを使ってユーザーの選択をSingularに通知します：

SingularCordovaSdk.limitDataSharing(false)を使用して、ユーザが情報の共有に同意した（オプトインした）ことを示します。

ユーザーが同意しなかった場合は、SingularCordovaSdk.limitDataSharing(true)を使用します。

Singularは"ユーザープライバシーのポストバック"でLimitDataSharingを使用し、関連する規制を遵守するために必要なパートナーにこの情報を渡します。詳しくは「ユーザーのプライバシーとデータ共有の制限」をご覧ください。

// ユーザーがデータ共有に同意した
cordova.plugins.SingularCordovaSdk.limitDataSharing(false);

GDPR 準拠のための追加メソッド

Singular SDKは、GDPRポリシーに準拠し、トラッキングに対するユーザーの同意または非同意についてSingularに知らせるためのメソッドをいくつか提供しています。

cordova.plugins.SingularCordovaSdk.trackingOptIn();

cordova.plugins.SingularCordovaSdk.stopAllTracking();

cordova.plugins.SingularCordovaSdk.resumeAllTracking();

cordova.plugins.SingularCordovaSdk.isAllTrackingStopped();