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プラグインを使用できるようになります：

   TypeScript

   import {Component} from '@angular/core';
   import {Platform} from '@ionic/angular';
   declare var cordova;
   ...
   
   export class HomePage {
   constructor(public platform: Platform) {
   this.platform.ready().then(() => {
   
       // Add code to initialize the Singular SDK here
   
   
   
   }); 
   }}
   

SDKの初期化（必須）

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

Singular SDKを初期化します：

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

   Meta Install Referrer "アトリビューションを有効にするために必要なSDKコンフィギュレーション：

   1. Singular Configuration ObjectにFacebook App Idを入力してください。
      

      // To enable META Install Referrer
      
      
      singularConfig.withFacebookAppId("INSERT YOUR FACEBOOK APP ID HERE");

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

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

// Create the configuration object


var singularConfig = new
cordova.plugins.SingularCordovaSdk.SingularConfig("<SDK KEY>", "<SDK SECRET>");

/*
// Optional: Enable deep linking (requires additional setup steps, see guide)


var linkHandler = function(data){
var deeplink = data.deeplink;
var passthrough = data.passthrough;
var isDeferred = data.isDeferred;
// Add link handling logic here


}
singularConfig.withSingularLink(linkHandler);
*/

/*
// To enable META Install Referrer


singularConfig.withFacebookAppId("INSERT YOUR FACEBOOK APP ID HERE");
*/

/*
// Optional: Enable SKAdNetwork (in Managed Mode, see guide for more options)


singularConfig.withSkAdNetworkEnabled(true);
*/

// Initialize Singular


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 メソッドを使います。イベントに名前を付け、追跡したい属性を追加します。

// Example: Report an event called View Product with event attributes


cordova.plugins.SingularCordovaSdk.eventWithArgs(
  'ViewProduct', // Event name


  {
    // Event attributes


    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, // E.g. "purchase"


  currencyCode, // E.g. "USD"


  purchaseAmount // E.g. 3.2


);

ハイブリッドイベント追跡（上級者向け）

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

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

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

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

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

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

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

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

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

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

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

   Java Kotlin

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

   import singular_cordova_sdk.SingularCordovaSdk
   
   override fun onNewIntent(intent: Intent) {
       SingularCordovaSdk.handleNewIntent(intent)
   }
   

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

   Swift Objective-C

   import UIKit
   import SingularCordovaSdk
   
   class AppDelegate: UIResponder, UIApplicationDelegate {
       
       var window: UIWindow?
       var viewController: MainViewController?
       
       func application(
           _ application: UIApplication,
           didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
       ) -> Bool {
           // Initialize window
   
           window = UIWindow(frame: UIScreen.main.bounds)
           
           // Configure view controller
   
           viewController = MainViewController()
           window?.rootViewController = viewController
           
           // Initialize Singular SDK
   
           SingularCordovaSdk.setLaunchOptions(launchOptions)
           
           // Make window visible
   
           window?.makeKeyAndVisible()
           
           return true
       }
       
       func application(
           _ application: UIApplication,
           continue userActivity: NSUserActivity,
           restorationHandler: @escaping ([Any]?) -> Void
       ) -> Bool {
           return SingularCordovaSdk.startSession(with: userActivity)
       }
   }
   

   #import "SingularCordovaSdk.h"
   #import "MainViewController.h"
   
   - (BOOL)application:(UIApplication *)application 
   didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
       // Initialize window
   
       self.window = [[UIWindow alloc] initWithFrame:[UIScreen mainScreen].bounds];
       
       // Configure view controller
   
       self.viewController = [[MainViewController alloc] init];
       self.window.rootViewController = self.viewController;
       
       // Initialize Singular SDK
   
       [SingularCordovaSdk setLaunchOptions:launchOptions];
       
       // Make window visible
   
       [self.window makeKeyAndVisible];
       
       return YES;
   }
   
   - (BOOL)application:(UIApplication *)application
   continueUserActivity:(NSUserActivity *)userActivity
   restorationHandler:(void (^)(NSArray<id> *))restorationHandler {
       return [SingularCordovaSdk startSessionWithUserActivity:userActivity];
   }
   

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

   JavaScript

   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;
     // Add link handling logic here
   
   
   }
   
   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("", "");

// Enable SKAdNetwork (in managed mode by default)


singularConfig.withSkAdNetworkEnabled(true);

cordova.plugins.SingularCordovaSdk.init(singularConfig);

マニュアルモード

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

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

var singularConfig = new
  cordova.plugins.SingularCordovaSdk.SingularConfig("<SDK KEY>", "<SDK SECRET>");

// Enable SKAdNetwork


singularConfig.withSkAdNetworkEnabled(true);

// Select SKAdNetwork manual mode


singularConfig.withManualSkanConversionManagement();

// Optional: define handler to track changes to the conversion value


var conversionHandler = function(updatedConversionValue){
  // Do something with updatedConversionValue


}

singularConfig.withConversionValueUpdatedHandler(conversionHandler);

// Initialize the Singular SDK


cordova.plugins.SingularCordovaSdk.init(singularConfig);

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

cordova.plugins.SingularCordovaSdk.skanUpdateConversionValue(
  newConversionValue,
  function(isSuccess){
    // isSuccess == true if the update was successful


  }
)

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

cordova.plugins.SingularCordovaSdk.skanGetConversionValue(
  function(conversionValue){
    // Do something with 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,
    {
        // Tracking link parameters to add to the short link, e.g. "channel":"sms"


        param1: value1,
        param2: value2,
        ...
    },
    {
        onSuccess: function (shortLinkURL) {
        // Do something with shortLinkURL


        },
        onError: function (error) {
        // Handle error


        }
    }
)

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

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

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

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

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

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

// User has opted into sharing data


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