サーバーからサーバー(S2S)統合ガイド

注: サーバー間の統合はご要望がある場合のみ可能です。 SingularカスタマーサービスマネージャーまたはSingularサポートにご相談ください。

 

アプリケーションに組み込む必要があるSingular SDKの代わりに、SingularはREST APIも提供しています。

このガイドでは、Singularで基本的なS2Sインテグレーションを構築し、様々なオプション機能を実装する方法を説明します。

S2S APIエンドポイントの全リスト、パラメータ、サンプルコールについては S2Sエンドポイントリファレンスを参照して下さい。

基本的な統合

Singularとの最も基本的な統合は、新しいセッションがあるとSingularに知らせることです。

ユーザーセッションをSingularに通知するにはセッション通知エンドポイントを呼び出します

セッション通知によってSingularはいくつかのことができるようになります:

  • 特定のデバイスでのアプリの最初のセッションであれば、Singularは新規インストールを認識し、インストールのアトリビューションプロセスをトリガーします。
  • セッションがリエンゲージメントセッションである場合、Singularはリエンゲージメントアトリビューションプロセスをトリガーします(詳しくはリエンゲージメントFAQをご覧ください)。
  • そうでない場合、Singularはそのセッションをセッションとしてマークし、ユーザーのアクティビティとリテンションのトラッキングに使用します。

セッション通知エンドポイントにはいくつかの必須パラメータがあります。セッションを報告するために必要なすべてのデータを取得する方法については、リファレンスを参照してください:iOS Install Receiptの取得と Reference:デバイス識別子とセッションデータの取得を参照してください。

ヒント セッションを報告するためのデータを収集するときは、非同期関数が返されるのを待って、さまざまなエッジケースを処理するようにしてください。 これは、データの欠落や部分的な帰属を引き起こす可能性のある一般的な問題です。

アプリセットIDの収集と送信(Android 12以上で必須)

App Set IDまたはASIDは、Android 12+デバイスで使用される、プライバシーに配慮した新しいIDです。App Set IDは、同じ開発者によってGoogle Playストアで公開されたデバイス上のすべてのアプリで共有されます。

GAID を送信する方法と同様に セッションコールとすべてのイベントコールのパラメータとして、App Set ID を追加します。

アプリセットIDを収集するには、アプリで以下のコードを使用します:

Context context = getApplicationContext();
  AppSetIdClient client = AppSet.getClient(context);
  Task<AppSetIdInfo> task = client.getAppSetIdInfo();
  
  task.addOnSuccessListener(new OnSuccessListener<AppSetIdInfo>() {
      @Override
      public void onSuccess(AppSetIdInfo info) {
          // Android アプリセット ID の現在のスコープを決定します。
          int scope = info.getScope();
  
          // UUID バージョン 4 形式を使用する Android アプリセット ID 値を読み取ります。
          String id = info.getId();
      }
  });

重要:Google Playのインストールリファラーを送信する(Android)

インストールリファラーには、ユーザーをGoogle Playストアに送信したユーザーに関する情報が含まれています。インストールリファラーがSingularで利用可能な場合、インストールを属性化する最も正確な方法を提供します。この値を取得し、最初のセッション通知コールで Singular に渡します。 User-Level Exports で Facebook のデータを受け取ったり、Data Destinations と共有したり、ポストバックを送信したりといった、Singular の重要な機能にはこの値が必要です。

Google Playは、ユーザーがストアに到着したときにリファラー情報を収集します。Google Playは、ユーザーがストアにアクセスした際にリファラー情報を収集し、ユーザーがアクセスしたアプリをインストールすると、そのアプリがその情報を利用できるようにします。詳細については、Googleの開発者向けドキュメントを参照してください。

インストールリファラーをSingularと共有するには:

  1. アプリが初めて開かれたときに、Play Install Referrer APIを使ってインストールリファラーを取得します。
  2. パラメータinstall_ref を含むセッション通知エンドポイントを使用して、Singular にセッションを報告します。このパラメータは JSON エンコードされ、以下の属性を持ちます:

    属性 属性説明
    referrer Play Install Referrer API から取得されたリファラー値。 これは JSON オブジェクトなので、必ず文字列としてエンコードしてください。
    referrer_source 特定 "service".
    clickTimestampSeconds Play Install Referrer API から受信したクリックのタイムスタンプ (例: "1550420123")。
    installBeginTimestampSeconds
    Play Install Referrer API から受け取った、インストールが開始された時刻。
    current_device_time 現在のデバイスの時間 (ミリ秒単位) (例: "1550420454906")。

以下は、インストールリファラーイベントを報告するためのサンプルコードです:

Python HTTP
import requests
import json
  
  SDK_KEY = '[開発者ツール>SDK統合>SDKキーのsdk_key]。'
  LAUNCH_URL = 'https://s2s.singular.net/api/v1/launch'
  
  referrer_values = {
        "referrer": "tracking_id%3D123456789&utm_source%3Dmdotm%26utm_medium%3Dbanner%26utm_campaign%3Dcampaign",
        "referrer_source" : "service",
        "clickTimestampSeconds" : 1550420123,
        "installBeginTimestampSeconds" : 1550420123,
        "current_device_time" : 1550420454906
      }

referrer_values = json.dumps(referrer_values, separators=(',',':')) params = { 'a': SDK_KEY, 'p': 'Android', 'i': 'com.singular.app', 'ip': '10.1.2.3', 've': '9.2', 'ma': 'samsung', 'mo': 'SM-G935F', 'lc': 'en_US', 'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b', 'andi': 'fc8d449516de0dfb', 'utime': 1483228800, 'dnt': 0, 'install':'true', 'n': 'MyCoolApp', 'c': 'wifi', 'cn': 'Comcast', 'bd': 'Build/13D15', 'fcm':'bk3RNwTe3H0CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1', 'app_v':'1.2.3', 'openuri':'myapp%3A%2F%2Fhome%2Fpage%3Fqueryparam1%3Dvalue1', 'ddl_enabled':'false', 'install_source': 'com.android.vending', 'install_time': 1510040127, 'update_time': 1510090877, 'custom_user_id': '123456789abcd', 'install_ref' : referrer_values } result = requests.get(LAUNCH_URL, params=params) print result.json()

オプションユーザIDの送信

新しいセッションをSingularに通知するときに、ユーザIDを追加することができます。これはユーザ名、メールアドレス、ランダムに生成される文字列、あるいはアプリがユーザIDとして使う識別子のどれでもかまいません。Singularはユーザーレベルのデータエクスポートや内部BIポストバック(設定されている場合)でユーザーIDを使用します。

ユーザーIDを送信するには セッション通知エンドポイントを呼び出すときに「custom_user_id」パラメータを追加します。

たとえば、次のようになります:

Python HTTP cURL
import requests
import json
  
  SDK_KEY = '[開発者ツール>SDK統合>SDKキーのsdk_key]。'
  LAUNCH_URL = 'https://s2s.singular.net/api/v1/launch'
  
  params = {
    'a': SDK_KEY,
    'p': 'Android',
    'i': 'com.singular.app',
    'ip': '10.1.2.3',
    've': '9.2',
    'ma': 'samsung',
    'mo': 'SM-G935F',
    'lc': 'en_US',
    'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
    'andi': 'fc8d449516de0dfb',
    'utime': 1483228800,
    'dnt': 0,
    'install':'true',
    'n': 'MyCoolApp',
    'c': 'wifi',
    'cn': 'Comcast',
    'bd': 'Build/13D15',
    'fcm':'bk3RNwTe3H0CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1',
    'app_v':'1.2.3',
    'openuri':'myapp%3A%2F%2Fhome%2Fpage%3Fqueryparam1%3Dvalue1',
    'ddl_enabled':'false',
    'install_source': 'com.android.vending',
    'install_time': 1510040127,
    'update_time': 1510090877,
    'custom_user_id': 'player_id_1234'
  }
  
  result = requests.get(LAUNCH_URL, params=params)
  print result.json()

追加のアトリビューション処理

Apple Search Adsキャンペーン(iOS)のアトリビューション

Apple Search AdsはSelf-Attributing Network(SAN)とみなされます。 iOS 14.3の時点で、Apple Search Adsの統合は2つのiOSフレームワークでサポートされています:

  • iOS 14.2以下では、Apple Search AdsはiAdフレーム ワークを介してサポートされています。
  • iOS 14.2以下では、Apple Search AdsはiAdフレームワークでサポートされます。iOS 14.3以上では、Apple Search AdsはAdServicesフレームワークでサポートされます。

iAdフレームワークが将来廃止されるまで、iAdフレームワークとAdServicesフレームワークの両方を実装することをお勧めします。 AdServicesはまだ新しいAppleのサービスであるため、Singularは両方のサービスを利用しますが、アトリビューションとレポートについてはiAdシグナルよりもAdServicesを優先します。

詳細については、Apple Search Adsの統合に関するドキュメントをご覧ください。

iAd経由でApple Search Adsを実装する(iOS 14.2以下)

1.アトリビューションデータの取得

アトリビューションデータを取得するには、Apple SearchAds iAd API を使用します。requestAttributionDetails(_:)を呼び出すと、アトリビューションデータを含む JSON オブジェクトが返されます。

Objective-C
#import <iAd/iAd.h>
  
    Class ADClientClass = NSClassFromString(@"ADClient");
  
    if (ADClientClass) {
        id sharedClient = [ADClientClass performSelector:@selector(sharedClient)];
        
        if ([sharedClient respondsToSelector:@selector(requestAttributionDetailsWithBlock:)]) {
            [sharedClient requestAttributionDetailsWithBlock:^(NSDictionary *attributionDetails, NSError *error) {
                if (attributionDetails && attributionDetails.count > 0) {
                    // iAd アトリビューションの詳細をアプリからサーバーに送信します。
                }
            }];
        }
    }
警告 Search Ads広告をクリックしたユーザーは、すぐにアプリをダウンロードして開くことがよくあります。通信に遅延がある場合、SingularのようなMMPは、アプリを開いてSearch Ads Attribution APIを呼び出す前に、広告クリックを受信して処理することができない可能性があります。これを防ぐため、Appleは以下を推奨している:
  1. アトリビューションデータを取得する前に数秒の遅延を設定する。
  2. レスポンスがFalseまたはエラーコード(0、2、3)の場合、リトライロジックを実装する。2秒後に再度Apple Attribution APIを呼び出す。

2.アトリビューションデータをSingularに送信する:

アトリビューションデータをSingularと共有するには、Event Notificationエンドポイントを使用して、予約イベント名__iAd_Attribution__でイベントを報告します。以下の例のように、前のステップで取得した JSON オブジェクトをe パラメータの 値として渡します。

Python HTTP
import requests
import json
  
  SDK_KEY = '[開発者ツール>SDK統合>SDKキーのsdk_key]。'
  EVENT_URL = 'https://s2s.singular.net/api/v1/evt'
  
  # !!! REPLACE WITH COLLECTED VALUE FROM APP !!!
  apple_attribution_data = {
    u'Version3.1': {
        u'iad-adgroup-id': u'1234567',
        u'iad-adgroup-name': u'Ad Group Name',
        u'iad-attribution': u'true',
        u'iad-campaign-id': u'1234567',
        u'iad-campaign-name': u'Search Campaign',
        u'iad-click-date': u'2016-05-21T12:19:31Z',
        u'iad-conversion-date': u'2016-05-21T12:19:41Z',
        u'iad-keyword': u'ballon',
        u'iad-lineitem-id': u'1234567',
        u'iad-lineitem-name': u'Line Item Name',
        u'iad-org-name': u'Cool Company',
        u'iad-purchase-date': u'2016-05-21T12:19:41Z'
    }
  }
  
  params = {
    'n': '__iAd_Attribution__',
    'e': json.dumps(apple_attribution_data),
    'a': SDK_KEY,
    'p': 'iOS',
    'i': 'com.singular.app',
    'ip': '10.1.2.3',
    've': '9.2',
    'mo': 'iPhone9%2C4',
    'lc': 'en_US',
    'idfa': '8ECD7512-2864-440C-93F3-A3CABE62525B',
    'idfv': '38548D9F-3F73-4D4B-8545-9A920CC89191',
    'utime': 1483228800
  }
  
  result = requests.get(EVENT_URL, params=params)
  print result.json()

注意事項

  • iOS 13+の場合、インストールまたは再インストール後の最初のセッションの直後に __iAd_Attribution__イベントを送信する必要があります。 そうしないと、Apple Search Adsのデータはアトリビューションの対象となりません。
  • iOS 14+では、Apple Search Adsのアトリビューション応答は特定の条件下でのみ利用可能で、AppTrackingTransparencyステータスがATTrackingManager.AuthorizationStatus.deniedの場合は利用できません。

AdServicesによるApple Search Adsの実装(iOS 14.3以上)

1.アトリビューショントークンの取得

attributionToken() を使用してアトリビューショントークンを取得します。

Objective-C
#import <AdServices/AdServices.h> 

NSError *error = nil;
Class AAAttributionClass = NSClassFromString(@"AAAttribution");
if (AAAttributionClass) {
NSString *attributionToken = [AAAttributionClass attributionTokenWithError:&error];
if (!error && attributionToken) {
// AdServices AttributionToken をアプリからサーバーに送信します。
}
}

注意事項

  • 帰属トークンはデバイス上で生成されます。
  • 5分後にattributionToken()が呼び出されると、新しいトークンが生成されます。
  • 生成されたトークンは24時間有効です。

2.アトリビューショントークンをSingularに送信します:

トークンをURLエンコードし、&attribution_token=パラメータに追加して、セッション通知エンドポイント経由でSingularに送信します。 このトークンは、SingularがApple Search Adsのダウンロードと再ダウンロードを追跡できるようにするため、インストールと再インストールのたびに最初のセッションで送信する必要があります。

メタインストールリファラーアトリビューション(Android)

Meta Referrer」は、Androidアプリのインストールに関する詳細なユーザーレベルのアトリビューションデータに広告主がアクセスできるようにするために、Facebookが導入したAndroid固有の測定ソリューションです( Facebookのデータポリシーを 参照 Google Play Install Referrer」(「Passing Google Install Referrer」を参照)と「Meta Install Referrer」の両方のテクノロジーを実装することで、アプリインストールの測定が可能になります。Met a Referrer詳細については、このトピックに関する FAQ を参照してください。

Meta InstallReferrer情報をSingnularと共有するには

  1. アプリを初めて開いたときに、Metaのドキュメントに従って Meta インストールリファラーを取得します。
  2. パラメータmeta_refを含むセッション通知エンドポイントを使用して、Singularにセッションを報告します。このパラメータはJSONエンコードされており、以下の属性を持ちます:

    属性 属性説明
    is_ct メタ インストール リファラーから受信した「is_ct」。 (例: 0 または 1)
    install_referrer メタ インストール リファラーから受信した「install_referrer」
    actual_timestamp メタ インストール リファラーから受信した「actual_timestamp」 (例: 1693978124)。

イベントのトラッキング

Singularはアプリ内イベントのデータを収集し、マーケティングキャンペーンのパフォーマンス分析に役立てることができます。イベントには、ログインや登録からゲームアプリのレベルアップまで、あらゆるユーザーインタラクションが含まれます。

SDK/S2SをSingularと統合する前に、貴社がトラッキングしたいイベントのリストを用意してください(アプリ内イベントの定義参照)。

アプリ内でイベントが発生したときにSingularに通知するには、Event Notificationエンドポイントを呼び出します。 呼び出しに含めるイベント名は、Singularのレポート、エクスポート、ポストバックでイベントを識別する方法です。

注意事項

  • Singularは、Singularの標準イベントと属性の命名規則を使用してイベントを渡すことを推奨します。 標準イベントを使用することで、マッピングが合理化され、統合におけるパートナーの標準イベントとの互換性が向上します。
  • サードパーティのパートナーや分析ソリューションとの互換性のために、イベント名やその他の属性を英語で渡すことを強くお勧めします。
  • イベント名は32 ASCII文字に制限されています。非ASCII文字の場合、UTF-8に変換されると32バイトに制限されます。
  • イベントの属性と値は500 ASCII文字に制限されています。

収益のトラッキング

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

収益イベントを追跡するには、すべてのイベントに使用するのと同じイベント通知エンドポイントを使用しますが、以下の情報を追加します:

  • is_revenue_event=true:イベントを収益イベントとしてマークします。イベント名が__iap__の場合、または金額が0より大きい場合は、このパラメータを省略できます。
  • Purchase receipt: AndroidまたはiOSのアプリ内課金(IAP)プロセスから返されるオブジェクトです。このレシートをSingularに渡すと、Singularにトランザクションの詳細が表示され、Singularのレポートがより充実したものになります。
  • 購入署名(Androidのみ): トランザクションを検証し、アプリ内詐欺に対抗するために、このデータをSingularに渡すことを強くお勧めします。
  • 売上金額(例:"amt=1.99")。
  • 通貨(ISO 4217の通貨コードを使用します。

購入レシートの取得

収益イベントが発生した後、購入レシートを取得してSingularに送信する方法を説明します:

  • Androidの場合:Google Playは購入レシート(「アプリ内購入データ」)と購入署名(「アプリ内データ署名」)を取得するAPIを提供しています。getBuyIntent()メソッドを使用してください。
  • iOSの場合以下の例に示すように、AppleのIn-App Purchases APIを使用します(詳細については、Apple In-App Purchases APIを参照してください)。
Objective-C
// SKPaymentTransactionObserver
    + (void)paymentQueue:(id)queue updatedTransactions:(NSArray *)skTransactions {
       NSString *transactionReceipt = nil;
  
       if ([skTransaction respondsToSelector:@selector(transactionReceipt)]) {
          NSData *transactionReceiptRaw = [skTransaction performSelector:@selector(transactionReceipt)];
          if (transactionReceiptRaw) {
             transactionReceipt = [ApUtils base64Encode:transactionReceiptRaw];
          }
       }
    }

カスタム収益イベントのサンプル

Python HTTP cURL
import requests
import json SDK_KEY = '[開発者ツール>SDK統合>SDKキーのsdk_key]。' EVENT_URL = 'https://s2s.singular.net/api/v1/evt' params = { 'a': SDK_KEY, 'p': 'Android', 'i': 'com.singular.app', 'ip': '10.1.2.3', 've': '9.2', 'ma': 'samsung', 'mo': 'SM-G935F', 'lc': 'en_US',
'bd': 'Build/13D15', 'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b', 'utime': 1483228800, 'n': 'RevenueEventName',
'amt': '2.50', 'cur': 'USD',
'is_revenue_event': 'true',
'purchase_receipt': {'orderId"':'GPA.1234',
'packageName':'com.example',
'productId':'com.example.product',
'purchaseTime':1417113074914,
'purchaseState':0,
'purchaseToken':'hakfcimbk... pM'},
'receipt_signature': 'TyVJfHg8OAoW7W4wuJt...5agEDMnNXvhfrw==',
'purchase_product_id': 'com.example.product',
'purchase_transaction_id': 'GPA.1234-1234-1234-12345' } result = requests.get(EVENT_URL, params=params) print result.json()

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

ディープリンクは、アプリ内の特定のコンテンツにつながるリンクです。アプリがインストールされたデバイス上でユーザーがディープリンクをクリックすると、アプリが開き、特定の製品や体験が表示されます。

シンギュラートラッキングリンクは、ディープリンクだけでなく、ディファードディープリンクも含むことができます(詳しくは、 ディープリンクFAQと シンギュラートラッキングリンクFAQをご覧ください)。

ディープリンクの前提条件

iOSの場合:

Androidの場合:

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

アプリがディープリンクで開かれた場合は必ず、openuriパラメータを使ってSingularにセッションを報告する際にURLを追加してください。これはSingular Linksを使用する場合に必要です。

ディファードディープリンクの有効化

インストール後に初めてアプリが開かれた場合、Singularにセッションを報告する際に以下のパラメータを追加して、遅延ディープリンクフローを有効にします:

  • install=true
  • ddl_enabled=true

Singularは、アプリが遅延ディープリンクを含むトラッキングリンクを通じてインストールされたかどうかを確認します。もしそうであれば、この呼び出しは以下の値を返します:

  • deferred_deeplink- ディープリンクアドレス。これは、ユーザーに正しい製品や体験を表示するために解析する必要があるものです。
  • deferred_passthrough- ディープリンクに追加されたパススルーパラメータ。

ディファードディープリンクをサポートしたセッション通知呼び出しのサンプル

Python
import requests
import json
  
      SDK_KEY = '[開発者ツール>SDK統合>SDKキーのsdk_key]。'
      LAUNCH_URL = 'https://s2s.singular.net/api/v1/launch'
  
      params = {
          'a': SDK_KEY,
          'p': 'iOS',
          'i': '162738612',
          'ip': '10.1.2.3',
          've': '9.2',
          'mo': 'iPhone9%2C4',
          'lc': 'en_US',
          'idfa': '8ECD7512-2864-440C-93F3-A3CABE62525B',
          'idfv': '38548D9F-3F73-4D4B-8545-9A920CC89191',
          'utime': 1483228800,
          'dnt': 0,
          'n': 'MyCoolApp',
          'c': 'wifi',
          'cn': 'Comcast',
          'bd': 'Build/13D15',
          'openuri':'https://myapp.sng.link/A59c0/nha7?_dl=myapp%3A%2F%2Fdeeplink&_ddl=myapp%3A%2F%2Fdeferred-deeplink&_p=passthroughvalue',
          'install':'true',
          'ddl_enabled':'true'
      }
  
      result = requests.get(LAUNCH_URL, params=params)
      print result.json()

サンプルレスポンス

{
    "deferred_deeplink":"myapp://deferred-deeplink",
    "status":"ok",
    "deferred_passthrough":"passthroughvalue"
  }

特異なショートリンクの処理

アプリがSingularショートリンクから開かれた場合、openuriで送られたurlがSingularロングリンクに解決されるべきことをSingularエンドポイントに通知するために、起動リクエストで以下のパラメータを送る必要があります。

  • singular_link_resolve_required=true

Singular はロングリンクを返し、アプリ開発者はリンクハンドラでディープリンクとパススルーパラメータを解析できます。

ショートリンクを解決するセッション通知呼び出しのサンプル

Python
import requests
import json
  
      SDK_KEY = '[開発者ツール>SDK統合>SDKキーのsdk_key]。'
      LAUNCH_URL = 'https://s2s.singular.net/api/v1/launch'
  
      params = {
          'a': SDK_KEY,
          'p': 'iOS',
          'i': '162738612',
          'ip': '10.1.2.3',
          've': '9.2',
          'mo': 'iPhone9%2C4',
          'lc': 'en_US',
          'idfa': '8ECD7512-2864-440C-93F3-A3CABE62525B',
          'idfv': '38548D9F-3F73-4D4B-8545-9A920CC89191',
          'utime': 1483228800,
          'dnt': 0,
          'n': 'MyCoolApp',
          'c': 'wifi',
          'cn': 'Comcast',
          'bd': 'Build/13D15',
          'openuri':'https://myapp.sng.link/A59c0/nha7/q5a2',
          'singular_link_resolve_required':'true',
      }
  
      result = requests.get(LAUNCH_URL, params=params)
      print result.json()

サンプルレスポンス

{
    "status":"ok",
    "resolved_singular_link":"https://myapp.sng.link/A59c0/nha7?_dl=myapp%3A%2F%2Fdeeplink&_ddl=myapp%3A%2F%2Fdeferred-deeplink&_p=passthroughvalue"
  }

動的パススルーパラメータのサポート

Singular のトラッキングリンクには、動的パススルーパラメータを含めることができます(詳細)。組織でリンクに動的パススルーパラメータを設定している場合、ディープリンクの URL には_pパラメータに続いて URL エンコードされた JSON 値または構造化されていない文字列が含まれ、適切なコンテンツやエクスペリエンスをユーザーに表示するために使用できます。

高度なオプション

Singular S2S連携は以下の高度な機能をサポートしています。これらは上記のAPIエンドポイントを使用して実装されますが、特別なパラメータと要件があります。

アンインストールの追跡

Singularはデバイスのサイレントプッシュ通知を使って、アンインストールを追跡できます。これを有効にするには、セッション通知ごとにデバイスのプッシュトークンをSingularサーバーに送信する必要があります。

Androidでのアンインストールの追跡

Androidでアンインストールのトラッキングを有効にするには、まずFirebaseInstanceId.getInstance().getToken()を呼び出してアプリからFCMトークンを取得します。トークンがまだ生成されていない場合、このメソッドはNULLを返します。詳細はGoogle Firebase ドキュメント を参照ください。

次の例のように、Singular にセッションを報告するときにfcmパラメータにデバイストークンを渡します:

Python HTTP cURL
import requests
import json
  
  SDK_KEY = '[開発者ツール>SDK統合>SDKキーのsdk_key]。'
  LAUNCH_URL = 'https://s2s.singular.net/api/v1/launch'
  
  params = {
    'a': SDK_KEY,
    'p': 'Android',
    'i': 'com.singular.app',
    'ip': '10.1.2.3',
    've': '9.2',
    'ma': 'samsung',
    'mo': 'SM-G935F',
    'lc': 'en_US',
    'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
    'andi': 'fc8d449516de0dfb',
    'utime': 1483228800,
    'dnt': 0,
    'n': 'MyCoolApp',
    'c': 'wifi',
    'cn': 'Comcast',
    'bd': 'Build/13D15',
    'fcm': 'bk3RNwTe3H0CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1'
  }
  
  result = requests.get(LAUNCH_URL, params=params)
  print result.json()

iOSのアンインストールを追跡する

SingularはAppleのプッシュ通知を使ってiOSのアンインストールを追跡できます。アプリがまだプッシュ通知に対応していない場合は、Appleのガイドを参照してください。 アプリがプッシュ通知に対応したら、Singularにセッションを報告するときにAPNSから返されたデバイストークンを渡してください。

注意事項

  • すでにプッシュ通知の実装があり、そこからデバイストークンを取得しているものとします。
  • APNSトークンは通常ネイティブ形式のバイナリデータです。APNSから受け取ったトークンをそのままSingularに渡してください。もしあなたのアプリがトークンのデータ型を別の目的のために変更する場合は、必ず16進エンコードされた文字列として渡してください(例: encodedb0adf7c9730763f88e1a048e28c68a9f806ed032fb522debff5bfba010a9b052
Python HTTP cURL
import requests
import json
  
  SDK_KEY = '[開発者ツール>SDK統合>SDKキーのsdk_key]。'
  LAUNCH_URL = 'https://s2s.singular.net/api/v1/launch'
  
  params = {
    'a': SDK_KEY,
    'p': 'iOS',
    'i': '162738612',
    'ip': '10.1.2.3',
    've': '9.2',
    'mo': 'iPhone9%2C4',
    'lc': 'en_US',
    'idfa': '8ECD7512-2864-440C-93F3-A3CABE62525B',
    'idfv': '38548D9F-3F73-4D4B-8545-9A920CC89191',
    'utime': 1483228800,
    'dnt': 0,
    'n': 'MyCoolApp',
    'c': 'wifi',
    'cn': 'Comcast',
    'bd': 'Build/13D15',
    'apns_token': 'b0adf7c9730763f88e1a048e28c68a9f806ed032fb522debff5bfba010a9b052'
  }
  
  result = requests.get(LAUNCH_URL, params=params)
  print result.json()

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

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

ユーザーに情報共有の同意を求める方法を実装している場合は、data_sharing_optionsパラメータを使ってユーザーの選択をSingularに通知します:

  • limit_data_sharing":falseを渡すと、ユーザが情報の共有に同意した(オプトインした)ことを示します。
  • ユーザーが拒否した場合は"limit_data_sharing":true を渡します。

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

注意

  • このメソッドの使用は任意ですが、ユーザーがオプトインしたことが特に通知された場合に限り、パートナーがSingularと共有するアトリビューション情報があるかもしれません。
  • GETリクエストでJSONオブジェクトを渡す場合は、忘れずにURLエンコードしてください。
フィールド タイプ 説明 使用方法
limit_data_sharing boolean

エンドユーザーの設定を示すために、すべての起動リクエストまたはEVTリクエストにこのオプションの値を渡します。

data_sharing_options=
%7B%22limit_data_sharing%22%3Atrue%7D

参照iOSのインストール・レシートの取得

Session Notificationエンドポイントのリファレンスにあるように、iOSアプリのセッションを報告するときには、install_receiptパラメータにインストール・レシートを渡す必要があります。

この値を取得するには、以下のコードをアプリに追加します:

Objective-C
+ (NSString*)installReceipt {
      // install receipts are iOS 7.0+
      if (NSFoundationVersionNumber < NSFoundationVersionNumber_iOS_7_0) {
          return nil;
      }
      
      NSURL *receiptURL = [[NSBundle mainBundle] appStoreReceiptURL];
      
      if (receiptURL) {
          NSData *receipt = [NSData dataWithContentsOfURL:receiptURL];
          
          if (receipt) {
              return [receipt base64EncodedStringWithOptions:0];
          }
      }
      
      return nil;
  }

リファレンスデバイス識別子とセッションデータの取得

このセクションでは、REST API で必要な特定の値を取得する方法について説明します。これらの値は業界標準であり、AppleとGoogleにもドキュメントがあります。便宜上、いくつかのリファレンス実装を提供します。

Google Advertising ID/Limit Ad Tracking(Android識別子)の取得

アプリのAdvertising IDを取得するには、Google Play Services SDKが必要です。 AndroidManifest.xmlのapplication要素の子要素に以下のタグを追加します:

XML
<meta-data android:name="com.google.android.gms.version"
             android:value="@integer/google_play_services_version" />

アプリのビルドがAndroid 12/APIレベル31以上をターゲットにしている場合は、Google Advertising IDにアクセスするためのパーミッションを追加します:

XML
<uses-permission android:name="com.google.android.gms.permission.AD_ID" />

Google Advertising ID/Limit Ad Tracking パラメータを取得するサンプルコード:

Java
import com.google.android.gms.ads.identifier.AdvertisingIdClient;
import com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
import com.google.android.gms.common.GooglePlayServicesAvailabilityException;
import com.google.android.gms.common.GooglePlayServicesNotAvailableException;
import java.io.IOException;
  
  // この関数をメインスレッドから呼び出さないでください。 それ以外の場合は、IllegalStateException がスローされます。
  public void getIdAndLAT() {
      Info adInfo = null;
      try {
          adInfo = AdvertisingIdClient.getAdvertisingIdInfo(mContext);
      } catch (IOException e) {
          // Google Play サービスへの接続時に回復不能なエラーが発生しました (古いバージョンのサービスは AdvertisingId の取得をサポートしていません)。
      } catch (GooglePlayServicesAvailabilityException e) {
          // Google Play サービスへの接続中に回復可能なエラーが発生しました。 
      } catch (GooglePlayServicesNotAvailableException e) {
          // Google Play サービスは完全には利用できません。
      }
  
final String GAID = adInfo.getId(); final boolean limitAdTracking = adInfo.isLimitAdTrackingEnabled(); }

Androidのロケール、デバイス、ビルドの取得

Java
  // Locale - lc= query parameter
  String locale = Locale.getDefault();
  
  // Model - mo= query parameter
  String device = Build.MODEL;
  
  // Build - bd= query parameter
  String build = "Build/" + Build.ID;

App Tracking Transparency認証ステータスの取得(iOS)

iOS 14.5以降、デバイスのIDFAを取得するにはApp Tracking Transparencyが必要です。App Tracking Transparencyプロンプトを表示する場合は、IDFAの取得を試みる前に、必ずプロンプトとハンドラを実装してください。

以下は、ATTプロンプト(オプション)の実装方法と、ATT認可像(必須)の取得方法の例である:

Objective-C
#import <AppTrackingTransparency/ATTrackingManager.h>
  
// ATT プロンプトを表示する場合はオプションです。 プロンプトを表示し、値を処理します。 複数回呼び出しても表示されるのは1回だけです。 [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status){ // your authorization handler here }];
// 必須 現在の ATT 認証ステータスを読み取ります。 ATTrackingManagerAuthorizationStatus status = [ATTrackingManager trackingAuthorizationStatus];

IDFA/広告追跡の制限(iOS識別子)の取得

iOS 14.5以降、IDFAを取得するにはApp Tracking Transparencyが必要です。App Tracking Transparencyのプロンプトを表示する場合は、IDFAを取得する前に必ずプロンプトとハンドラを実装してください。

App Tracking Transparencyを表示しない場合でも、IDFAの取得は可能です(値は0になります)。SingularはIDFAが利用できないか、すべてゼロの場合にフォールバックするので、IDFVはどのような場合でも取得して送信する必要があります。

limit-ad-track(isAdvertisingTrackingEnabled)フラグはiOS 13以下では必須で、ユーザーが広告トラッキングをオプトアウトしているかどうかを示すために使用されます。iOS 14以上では、このフラグは非推奨であり、取得された場合は静的な値となります。Singularとパートナーは、プライバシーフローのデータ処理について、より新しいATT認証ステータスの値に依存します。

以下はIDFA、IDFV、広告トラッキング制限ステータスの取得例です:

Objective-C Swift
// ファイルの先頭に AdSupport クラスをインポートします。
@import AdSupport;

IDFA/Limit Ad Trackingパラメータを取得するサンプルコード:

Objective-C Swift
NSString* IDFA = [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString];
  NSString* IDFV = [[[UIDevice currentDevice] identifierForVendor] UUIDString];
  
  BOOL isAdvertisingTrackingEnabled = [[ASIdentifierManager sharedManager] isAdvertisingTrackingEnabled];

iOSのロケール、デバイス、ビルドの取得

Objective-C Swift
  // Locale - lc= query parameter
  NSString *locale = [[NSLocale currentLocale] localeIdentifier];
  
  // Model - mo= query paramter
  #import <sys/sysctl.h>
  NSString *device() {
      size_t bufferSize = 64;
      NSMutableData * buffer = [[NSMutableData alloc] initWithLength:bufferSize];
      int status = sysctlbyname("hw.machine", buffer.mutableBytes, &bufferSize, NULL, 0);
      if (status != 0) {
          return nil; 
      }
      return [[NSString alloc] initWithData:buffer encoding:NSUTF8StringEncoding];
  }
  
  // Build - bd= query parameter
  NSString * build () { 
      size_t bufferSize = 64;
      NSMutableData *buffer = [[NSMutableData alloc] initWithLength:bufferSize];
      int status = sysctlbyname("kern.osversion",buffer.mutableBytes, &bufferSize, NULL, 0);
      if (status != 0) {
          return nil;
      }
      return [[NSString alloc] initWithData:buffer encoding:NSUTF8StringEncoding];
  }