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インストールリファラー帰属のサポート
   2025年6月18日より、MetaのAdvanced Mobile Measurement Reporting (AMM)では、Meta Install Referrerを実装する必要がなくなりました。AMMレポートが有効になっている場合、Meta Install Referrerを実装することは推奨されません。
   Meta Install Referrer」アトリビューションを有効にするには、SDKの設定が必要です：
   1. Singular Configuration ObjectにFacebookアプリ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);
*/

// Initialize Singular
cordova.plugins.SingularCordovaSdk.init(singularConfig);

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

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

その他のオプション

アンインストールの追跡

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