コルドバのSingularなSDK統合

 

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に送信することができます。

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

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

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

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

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

SingularCordovaSdk.setCustomUserIDメソッド
説明 ユーザーIDをSingularに送信します。
シグネチャ SingularCordovaSdk.setCustomUserId(String customUserId)
使用例
SingularCordovaSdk.setCustomUserId('CustomUserId');
SingularCordovaSdk.unsetCustomUserIDメソッド
説明 Singularに送信されたユーザーIDの設定を解除します。
シグネチャ SingularCordovaSdk.unsetCustomUserId()
使用例
SingularCordovaSdk.unsetCustomUserId();

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

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

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

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

SingularCordovaSdk.setDeviceCustomUserId メソッド
説明 ログイン時と同じカスタムユーザーIDを設定し、Singularのトラッキング識別子にマッピングします。
シグネチャ SingularCordovaSdk.setDeviceCustomUserId(String customUserId)
使用例
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)
  }

カスタム収益の送信

IAPオブジェクトをSingularに送信できない場合は、イベント名、通貨コード、購入金額を受け取るcustomRevenueメソッドを使用することもできます。

cordova.plugins.SingularCordovaSdk.customRevenue(
    customEventName, // 例 "purchase"

    currencyCode, // 例 "USD"

    purchaseAmount //  例 3.2

  );

注:通貨は3文字のISO 4217通貨コード("USD"、"EUR"、"INR "など)を渡します。

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

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

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

重要です

Server-to-Server イベントリクエストで使用されるデバイス識別子がSingularで一致しない場合、不一致が発生します。以下の可能性に注意してください:

  • イベントリクエストがSingular SDKがアプリセッションからデバイス識別子を記録する「前」に受信された場合、そのイベントリクエストは未知のデバイスの「最初のセッション」とみなされ、Singularはそのデバイスをオーガニックアトリビューションとしてアトリビュートします。
  • もしSingular SDKがデバイス識別子を記録していたとしても、Singular SDKの識別子がServer-to-Server Eventリクエストで指定されたデバイス識別子と異なる場合、イベントの帰属は正しくありません。

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

内部サーバーからのイベント送信

Singularはお客様のサーバーから収益に関するデータを収集し、キャンペーンのパフォーマンスやROIの分析に役立てることができます。

要件

  • アプリ内登録またはログインイベントから、デバイス識別子を取得して渡し、このデータをユーザーIDと共にサーバーに保存します。デバイス識別子はユーザーによって変更される可能性があるため、ユーザーがアプリセッションを生成する際には必ず識別子を更新してください。これにより、サーバー側イベントが正しいデバイスに帰属することが保証されます。
  • サーバー側イベントはプラットフォーム固有であるため、デバイスプラットフォームに一致するデバイス識別子(iOSデバイスのIDFAまたはIDFVなど)のみを使用して送信する必要があります。
  • Singular 内部 BI ポストバック メカニズムを使用して、内部エンドポイントにリアルタイムでイベントをプッシュすると、サーバー側でデータセットを更新できます。内部BI ポストバック FAQ を参照してください。
  • 詳細については、『サーバー間統合』ガイドの「収益の追跡」セクションを参照してください。
収益プロバイダからのイベントの送信
RevenueCatや adaptyのようなサードパーティプロバイダーは、Singularに購入収益や購読収益を提供することができます。

これらのパートナーを有効にする方法の詳細については、以下のリンクを参照してください。

セグメントからのイベント送信

SingularSDKと並行してSegmentからSingularにイベントを送信するには、Segmentに"Cloud-Mode "Destinationを追加する必要があります。こちらのガイドに従ってください。

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

SingularはGoogle AdMob、AppLovin、Unity LevelPlay (IronSource)、TradPlusなどのメディエーションプラットフォームと統合されており、広告収益のアトリビューションが可能です。また、Singularは一般的な広告収益SDKの統合により、他のメディエーションプラットフォームもサポートしています。

SingularSDKインテグレーションにコードスニペットを追加することで、メディエーションプラットフォームから広告収益アトリビューションデータを取得することができます。これにより、SKAdNetworkキャンペーンの広告収益データを取得することもできます。

メディエーション・プラットフォームからユーザーレベルの広告収入を得ることで、Singularはこのデータを受け入れることができるメディア・ソースに帰属広告収入を送り返し、AdROASキャンペーンを実施することができる。

SDKの実装に関する説明とコード・スニペットを参照してください。 [こちら].

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

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

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

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を使用し、関連する規制を遵守するために必要なパートナーにこの情報を渡します。詳しくは「ユーザーのプライバシーとデータ共有の制限」をご覧ください。

注意: このメソッドの使用は任意ですが、ユーザーがオプトインしたことが特に通知された場合のみ、パートナーがSingularと共有する属性情報があるかもしれません。

SingularCordovaSdk.limitDataSharing メソッド
シグネチャ SingularCordovaSdk.limitDataSharing(booleanshouldLimitDataSharing)
説明 個人データの共有に関するユーザーの同意(オプトイン)をSingularに通知します。Limit Data Sharing(データ共有の制限)メソッドは、アプリがユーザーデータをサードパーティに送信するかどうかを制御するオプションを提供します。これは、ユーザーの好みやプライバシー要件に基づいてデータ共有を制限したい場合に便利です。
使用例
// ユーザーがデータ共有に同意した

cordova.plugins.SingularCordovaSdk.limitDataSharing(false);

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

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

SingularCordovaSdk.trackingOptIn メソッド
説明 トラッキングに対するユーザーの同意(オプトイン)をSingularに通知する。TrackingOptIn()メソッドは、「gdpr 」イベントをSingularサーバーに送信するために使用されます。このメソッドを呼び出さない場合、アプリはユーザーが同意したかのようにトラッキングを続けますが、特にGDPRオプトインとしてマークされることはありません。アプリがGDPR(一般データ保護規則)に準拠する必要がある場合は、ユーザーの同意が適切に記録されるように、この関数を呼び出す必要があります。
使用例
cordova.plugins.SingularCordovaSdk.trackingOptIn();
SingularCordovaSdk.stopAllTrackingメソッド
説明

このアプリにおけるこのユーザーのトラッキングをすべて停止します。

注意:このメソッドを呼び出すと、アプリが再起動した後でもSDKが効果的に無効になります(状態は永続的です)!トラッキングを再び有効にする唯一の方法は、resumeAllTracking()を呼び出すことです。
使用例
cordova.plugins.SingularCordovaSdk.stopAllTracking();
SingularCordovaSdk.resumeAllTrackingメソッド
説明 このアプリのこのユーザーのトラッキングを再開します。
使用
cordova.plugins.SingularCordovaSdk.resumeAllTracking();
SingularCordovaSdk.isAllTrackingStoppedメソッド
説明 このアプリのこのユーザーのトラッキング状況を確認します。StopAllTracking()を使用してトラッキングが停止され、再開されていない場合はtrueを返します。
使用例
cordova.plugins.SingularCordovaSdk.isAllTrackingStopped();