サーバー間統合ガイド
サーバー間の使用例
アプリケーションに組み込まなければならないSingular SDKの代わりに、Singular SDKを使わずに独自のサーバーから実行する完全な統合を構築するために使用できるREST APIも提供しています。このガイドでは、完全なサーバー間統合を構築するためのコンセプトを説明し、すべての高度な機能を紹介します。
ハイブリッド使用例
100%サーバー間統合の代わりに、Singular SDKを使ってセッション管理、すべての高度な機能、データ収集に対応するハイブリッドアプローチを利用することもできます。さらに、Server-to-Server EVENT APIを活用してバックエンドサーバーからイベントを送信します。
ハイブリッド使用例の詳細
アプリ外のモバイルイベントまたはウェブサイトのイベントデータをサーバーからSingularに送信する場合、Singular Mobile SDKまたはWeb SDKの対応する識別子を含めることが不可欠です。これにより、イベントアクティビティが正しいデバイスに正確に帰属するようになります。
データフロー
このデバイスデータを取得するには、主に2つの方法があります:
- クライアント管理データフロー:このオプションは、クライアントで必要なデータポイントをすべて取得し、独自のAPI経由でサーバーに渡します。この方法では、デバイス識別子、イベントデータ、その他必要な属性をクライアントサイド(モバイルアプリやウェブサイトなど)から直接収集し、サーバーに転送し、そこでServer-to-Server EVENT APIを使って処理してSingularに送ることができます。
- ポストバック:このオプションはSingular Internal BIのポストバックを設定するもので、SingularがJSONペイロードを使って指定のエンドポイントにポストバックを送信します。このポストバックは、インストール、リエンゲージメント、アプリ内イベントが発生した後にリアルタイムで配信されます。ペイロードには、アプリ外のサーバーサイドイベントを正常に送信するために必要なすべてのデータポイントが含まれます。内部 BI ポストバックの詳細な設定方法については、[こちら]をクリックしてください。
どちらのオプションでも、デバイス グラフを維持するためにサーバー側のロジックが必要になる場合があります。Singular SDKがデバイス識別子の変更を検出した場合、正確なトラッキングとアトリビューションを保証するために、サーバーを適宜更新することが重要です。
最初のオプション(アプリからデバイス識別子とパラメータを取得し、Singular API Endpointsで使用するためにサーバに送信する)を実装するには、以下の記事を参考にしてください:
- イベントエンドポイントの必須パラメータを確認する。
- 特定のデバイス識別子とデバイスデータポイントの取得を支援する iOS と Android のコードサンプルのServer-to-Server Retrieving Device Data Guideを確認してください。
以下の一般的なガイドラインを確認し、Server-to-Server構成の一般的なガイドラインに従います。ハイブリッドのユースケースでは、Singular SDKが管理しますので、SESSION Endpointを省略することができます。
キーポイント
- 柔軟性:データの収集と送信を完全にコントロール
- 機能の同等性:適切なデータが提供されれば、すべてのSDK機能をサポートします。
- 統合パスクライアント → お客様のサーバー → Singular API
- リアルタイム処理:一度に1つのリクエスト、バッチ処理なし。
- シーケンシャルなデータフロー:イベントは時系列に処理されなければならない。
- データの重複排除: Singularは受信したデータを重複排除しません。成功したリクエストを1つ送信し、リクエストが再生される場合に備えてログを保存しておくことを推奨します。
- データ検証: デバイスレベルのデータは永続的であり、一度取り込まれると削除できません。データをSingularに送信する前に徹底したデータ検証を行い、正確性を確保してください。
要件
SDKは自動的にデバイスとアプリのデータを収集しますが、S2Sアプローチでは以下のことが必要です:
- アプリから必要なデータポイントを収集する。
- このデータをサーバーに転送し、デバイスグラフに保存します。
- SESSION APIエンドポイントを介してSingularにセッションリクエストを送信します。
- Singularのレスポンスをアプリに戻します。
- EVENT API Endpointを使ってSingularにEventリクエストを送ります。
REST API エンドポイント
セッションエンドポイント
GET https://s2s.singular.net/api/v1/launch
セッションエンドポイント API リファレンス
イベントエンドポイント
GET https://s2s.singular.net/api/v1/evt
イベントエンドポイント API リファレンス
はじめに
アプリのセッションとイベントをトラッキングするSingularのREST APIをうまく統合するには、4つの重要なフェーズからなる包括的なデータパイプラインを実装する必要があります。
- アプリ内で堅牢なデータ収集戦略を確立し、関連するユーザーインタラクションとSingularが要求するデータポイントをキャプチャしてサーバーサイドのデータベースに保存します。
- 取り込んだイベントをサーバーからSingularのREST APIエンドポイントに即座に転送するリアルタイムのデータストリーミングメカニズムを構築する。
- 適切なレスポンス処理を実装してSingularのAPIレスポンスを処理し、データ転送の成功と適切なエラー管理を保証する。
- すべてのデータフローにわたって徹底的なテストを実施し、統合の正確性と信頼性を検証する。
この体系的なアプローチにより、お客様のアプリケーションとSingularの分析プラットフォーム間のデータの整合性とリアルタイムの同期を維持しながら、シームレスなデータ転送を実現します。
データ収集
Singularは各エンドポイントに特定のデータポイントを要求します。これらはSingularプラットフォームの機能を提供するために必要なものです。必要なパラメータはすべて必須で、省略するとデータや機能に矛盾が生じます。
ヒント: Singular APIで使用するために、クライアントサイドのデータを収集してサーバーに送り返す場合は、必ず非同期関数が戻ってくるのを待ち、様々なエッジケースに対処してください。これはよくある問題で、データの欠落や部分的な帰属を引き起こす可能性があります。
- Session Endpoint の必須パラメータを確認してください。
- Event Endpoint の必須パラメータを確認してください。
- 特定のデバイス識別子とデバイス・データ・ポイントの取得を支援するために、iOS と Android 用のコード・サンプルのServer-to-Server Retrieving Device Data Guideをレビューする。
- 特定のSkAdNetwork 4デバイス・データ・ポイントの取得を支援するため、iOS用コード・サンプル『Server-to-Server SKAdNetwork 4 Implementation Guide』を確認する。
- 以下の必要なアドバンスオプションのセクションを確認し、特定する。
必要なデータポイントを取得し、サーバーに提供することで、セッションとイベントリクエストをSingularにストリーミングする準備が整います。
リアルタイムデータストリーミング
リアルタイムのデータストリーミングは、正確なアトリビューションとキャンペーンパフォーマンス測定を維持するために非常に重要です。サーバーサイドトラッキングを実装する場合、データ送信のタイミングと順序は、Singularが提供する分析と最適化機能の品質に直接影響します。
重要なタイミングの考慮事項
- アトリビューションの精度:セッションレポートの遅延は、アトリビューションの精度に深刻な影響を与えます。ユーザーのアクションとマーケティングキャンペーンを正しく関連付けるには、正確な時間データが必要だからです。
- SKAdNetworkの影響:iOSのSKAdNetworkのコンバージョン値は時間に敏感なため、リアルタイムのデータストリーミングが特に重要になります。コンバージョン値の更新にはデバイス上のタイマーウィンドウが厳密に設定されているため、イベントレポートが遅れると、コンバージョン値を更新する機会を逃し、キャンペーンパフォーマンスデータが不完全または不正確になる可能性があります。
データストリームを構築する際に留意すべきベストプラクティスをいくつか紹介します:
- アプリのセッション開始用にサーバーサイドのイベントリスナーを実装する。
- セッションデータをSingularのREST APIに必要なデータポイントと共にすぐに転送する。
- アプリ内イベントのサーバーサイドイベントリスナーを実装する。
- イベントデータを必要なデータポイントと共にSingularのREST APIに即座に転送します。
- 信頼性の高いデータ転送のためにウェブフックアーキテクチャを使用する。
- 失敗したリクエストのリトライメカニズムを実装する。
- 品質保証のためにデータフローを監視する。
リアルタイムストリームを設定したら、レスポンス処理に進みます。
レスポンス処理
レスポンス処理は、サーバー側のAPIインタラクションとクライアント側の機能の橋渡しをするもう一つの重要なコンポーネントです。この双方向通信により、SingularのAPIからの貴重なレスポンスデータがモバイルアプリケーションに届くようになり、ディファードディープリンクやコンバージョン値の更新のような重要な機能が可能になります。
主なレスポンスタイプ
- 遅延ディープリンク:新しいセッションが開始されると、APIレスポンスに保留中のディープリンクデータが含まれることがあります。
- コンバージョン値:iOSキャンペーンの場合、コンバージョンエンドポイントは更新されたSKAdNetworkのコンバージョン値を提供し、正確なキャンペーン測定を維持するためにアプリに迅速に転送する必要があります。
レスポンス処理フローを構築する際に留意すべきベストプラクティスをいくつかご紹介します:
- クライアントサーバーでレスポンス処理を実装する。
- Singular API のレスポンスを解析し、検証します。
- 関連するレスポンスデータをクライアントアプリに転送する。iOSのSKAdNetworkコンバージョン値の更新に不可欠です。
- クライアント側のレスポンス処理を実装します。
- 適切なステータスコードで優雅にエラーを処理する。
- 再試行メカニズムのために失敗した応答を記録する。
レスポンス処理が完了したら、データパイプラインをテストし、すべてのデータフローが期待通りに機能し、正しいデータを提供することを検証します。
データフローのテスト
デプロイを成功させるには、テスト段階が重要である。Singularとの最も基本的な統合は、ユーザーセッションが発生するとSingularに通知し、Singularがいくつかの内部プロセスをトリガーできるようにすることである:
- 特定のデバイスでのアプリの最初のセッションであれば、Singularは新規インストールを認識し、インストールアトリビューションプロセスをトリガーする。
- セッションがリエンゲージメントセッションとして適格であれば、Singularはリエンゲージメントアトリビューションプロセスをトリガーします(詳しくはリエンゲージメントFAQをご覧ください)。
- そうでない場合、Singularはそのセッションをセッションとしてマークし、ユーザーのアクティビティとリテンションメトリクスのトラッキングに使用します。
Singularサーバーへのセッションリクエストとその後のイベントリクエストのタイミングは非常に重要です:
-
セッションはイベントの前に受け取らなければなりません。
例えば、ユーザーがアプリを使い始めると、Singular SDKはアプリオープンでセッションをトリガーします。ユーザーがアプリを長時間(1分以上)バックグラウンドに置くと、セッションはタイムアウトします。アプリをフォアグラウンドに戻すと、別のセッションが送信されます。アプリのライフサイクルイベントとタイマーを使ってセッションを管理し、Singularへのセッションリクエストを調整することをお勧めします。 - アプリで発生したイベントは、リアルタイムで、それぞれのセッションの後に送信されなければなりません。
- セッションデータフローをテストし、最初のセッションとその後のセッションがそれぞれのデータポイントと正しい値を持っていることを検証してください。
- イベントがSingularに報告された後にのみ受信されることを確認します。セッションが報告される前にイベントが受信された場合、そのデバイスに対して有機的なアトリビューションが作成され、報告において望ましくない結果を引き起こす可能性があります。
- セッションレスポンスが処理され、クライアントアプリに戻されることを確認する。これは、Singularキャンペーンでディファードディープリンクをサポートする場合に重要です。
成功しました:
- 必要なデータポイントのデータ収集と保存を検証しました!
- Singularへのリアルタイムデータストリーミングを検証しました!
- Singularへのリクエストのレスポンス処理とログを検証しました!
- すべてのテストデータフローを検証しました!
高度なオプション
SingularのS2S(Server-to-Server)統合の高度なオプションを利用するには、セッション通知エンドポイントを追加パラメータで拡張する必要があります。
このプロセスには以下が含まれます:
- 必要な高度な機能を特定する。
- 対応する特別なパラメータを見つける。
- これらのパラメータを既存のエンドポイント構成に組み込む。
利用可能な高度なオプションを以下に示します:
追加のアトリビューション処理
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フレーム ワークを介してサポートされています。
- iOS14.3以上では、Apple Search AdsはAdServicesフレームワークでサポートされています。
iAdフレームワークが将来廃止されるまで、iAdフレームワークとAdServicesフレームワークの両方を実装することをお勧めします。 AdServicesはまだ新しいアップルのサービスなので、Singularは両方のサービスを利用しますが、アトリビューションとレポートについてはiAdシグナルよりもAdServicesを優先します。
詳細については、Apple Search Adsの統合に関するドキュメントをご覧ください。
iAd経由でApple Search Adsを実装する(iOS 14.2以下)
1.アトリビューションデータの取得
アトリビューションデータを取得するには、Apple Search Ads iAd APIを使用します。requestAttributionDetails(_:)を呼び出すと、アトリビューションデータを含むJSONオブジェクトが返されます。
例えば
#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) {
// REPORT attributionDetails FROM YOUR APP TO YOUR SERVER
}
}];
}
}
- アトリビューションデータを取得する前に数秒の遅延を設定する。
- レスポンスがFalseまたはエラーコード(0、2、3)の場合、リトライロジックを実装する。2秒後に再度Apple Attribution APIを呼び出す。
2.アトリビューションデータをSingularに送信する:
アトリビューションデータをSingularと共有するには、Event Notificationエンドポイントを使用して、予約イベント名__iAd_Attribution__でイベントを報告します。以下の例のように、前のステップで取得した JSON オブジェクトをe パラメータの 値として渡します。
import requests
import json
SDK_KEY = '[sdk_key from Developer tools > SDK Integration > SDK keys]'
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()
https://s2s.singular.net/api/v1/evt?n=__iAd_Attribution__&e=%7B%22Version3.1%22%3A%7B%22iad-purchase-date%22%3A%20%222016-10-25T22%3A24%3A35Z%22%2C%22iad-keyword%22%3A%20%22ballon%22%2C%22iad-adgroup-id%22%3A%20%221234567%22%2C%22iad-campaign-id%22%3A%20%221234567%22%2C%22iad-lineitem-id%22%3A%20%221234567%22%2C%22iad-org-id%22%3A%20%224070%22%2C%22iad-org-name%22%3A%20%22Cool%20Company%22%2C%22iad-campaign-name%22%3A%20%22Search%20Campaign%22%2C%22iad-conversion-date%22%3A%20%222016-05-21T12%3A19%3A41Z%22%2C%22iad-conversion-type%22%3A%20%22Redownload%22%2C%22iad-click-date%22%3A%20%222016-05-21T12%3A19%3A31Z%22%2C%22iad-attribution%22%3A%20%22true%22%2C%22iad-adgroup-name%22%3A%20%22Ad%20Group%20Name%22%2C%22iad-lineitem-name%22%3A%20%22Line%20Item%20Name%22%7D%7D&a=SDK_KEY&p=iOS&i=com.singular.app&ip=10.1.2.3&ve=9.2&ma=Apple&mo=iPhone8%2C1&lc=en_US&idfa=8ECD7512-2864-440C-93F3-A3CABE62525B&idfv=38548D9F-3F73-4D4B-8545-9A920CC89191&utime=1568948680
注意事項
- 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() を使用してアトリビューショントークンを取得します。
例
#import <AdServices/AdServices.h>
NSError *error = nil;
Class AAAttributionClass = NSClassFromString(@"AAAttribution");
if (AAAttributionClass) {
NSString *attributionToken = [AAAttributionClass attributionTokenWithError:&error];
if (!error && attributionToken) {
// Handle attributionToken
}
}
注意事項
- 帰属トークンはデバイス上で生成されます。
- 生成後、トークンはデバイス上に5分間キャッシュされます。 5 分後に attributionToken() が呼び出されると、新しいトークンが生成されます。
- 生成されたトークンは24時間有効です。
2.アトリビューショントークンをSingularに送信します:
トークンをURLエンコードし、&attribution_token=パラメータに付加してセッション通知エンドポイント経由でSingularに送信します。 このトークンは、SingularがApple Search Adsのダウンロードと再ダウンロードを追跡できるようにするため、インストールと再インストール後の最初のセッションで送信する必要があります。
重要:Google Playインストールリファラーの送信(Android)
インストールリファラーには、誰がユーザーをGoogle Playストアに送り込んだかという情報が含まれています。インストールリファラーがSingularで利用可能な場合、インストールを属性化する最も正確な方法を提供します。この値を取得し、最初のセッション通知コールで Singular に渡します。 この値は、ユーザレベルエクスポートでFacebookのデータを受け取ったり、データ送信先と共有したり、ポストバックを送信したりといった、いくつかの重要なSingularの機能に必要です。
Google Playは、ユーザーがストアに到着したときにリファラー情報を収集します。Google Playは、ユーザーがストアにアクセスした際にリファラー情報を収集します。ユーザーがアクセス先のアプリをインストールした場合、Google Playはその情報をアプリに提供します。詳細については、Googleの開発者向けドキュメントを参照してください。
インストールリファラーをSingularと共有するには:
- アプリが初めて開かれたときに、Play Install Referrer APIを使ってインストールリファラーを取得します。
-
パラメータ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」)。
以下は、インストールリファラーイベントを報告するためのサンプルコードです:
import requests
import json
SDK_KEY = '[sdk_key from Developer tools > SDK Integration > SDK keys]'
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()
https://s2s.singular.net/api/v1/launch?aifa=8ecd7512-2864-440c-93f3-a3cabe62525b&andi=fc8d449516de0dfb&p=Android&a=SDK_KEY&i=com.singular.app&ip=10.1.2.3&ve=9.2&dnt=0&n=MyCoolApp&dnt=0&c=wifi&cn=Comcast&lc=en_US&bd=Build%2FMMB29K&ma=samsung&mo=SM-G935F&custom_user_id=123456789abcd&install_ref=%7B%22installBeginTimestampSeconds%22%3A%221568939453%22%2C%22referrer%22%3A%22utm_source%3Dgoogle-play%26utm_medium%3Dorganic%22%2C%22clickTimestampSeconds%22%3A%220%22%2C%22referrer_source%22%3A%22service%22%2C%22current_device_time%22%3A%221568944524%22%7D%0A
Meta Install Referrer Attribution (Android)
「Meta Referrer」は、広告主がAndroidアプリのインストールに関する詳細なユーザーレベルのアトリビューションデータにアクセスできるようにするために、Facebookが導入したAndroid固有の測定ソリューションです( Facebookのデータポリシーを参照 )。Google Play Install Referrer」(「Passing Google Install Referrer」を参照)と「Meta Install Referrer」の両方のテクノロジーを実装することで、アプリインストールの測定が可能になります。Meta Referrerの詳細については、このトピックに関するFAQをご覧ください。
Meta Install Referrer情報をSingnularと共有するには:
- アプリを初めて開いたときに、Metaのドキュメントに従って Meta インストールリファラーを取得します。
-
パラメータmeta_refを含むセッション通知エンドポイントを使用して、Singularにセッションを報告します。このパラメータはJSONエンコードされており、以下の属性を持ちます:
属性 属性 説明 is_ct
Meta Install Referrerから受け取った "is_ct"。(例: 0 または 1) install_referrer
Meta Install Referrerから受信した "install_referrer"。 actual_timestamp
Meta Install Referrerから受け取った "actual_timestamp"(例:1693978124)。
Singularリンクのサポート
ディープリンクは、アプリ内の特定のコンテンツにユーザーを導くクリック可能なリンクです。アプリがインストールされたデバイスでユーザーがディープリンクをクリックすると、アプリが開き、特定の製品や体験が表示されます。
シンギュラートラッキングリンクは、ディープリンクだけでなく、ディファードディープリンクも含むことができます(詳しくは、 ディープリンクFAQと シンギュラートラッキングリンクFAQをご覧ください)。
ディープリンクを有効にする
ディープリンクの前提条件
クライアントアプリがシンギュラーリンクをiOSユニバーサルリンクまたはAndroidアプリリンクとして認識するように設定されている必要があります。iOSとAndroidのディープリンクを有効にするには、「Singular Links Prerequisites」ガイドに従ってください。
ディープリンクの実装
ディープリンクを通じてアプリが開かれた場合、URL値をopenuri パラメータに追加することで、Singularに送信されるセッション通知リクエストにopenURLをキャプチャして追加します。これはSingular Linksを使用する場合に必要です。
クライアントアプリのコードを更新して、Singular LinksのURLからディープリンクパラメータを解析し、処理する必要があります。シンギュラーリンクによるディープリンクが成功した場合、openURLに以下のパラメータが存在する可能性があります:
_dl, _ios_dl, _android_dl, _p
- _ios_dl リンクがiOSとAndroidの両方でディープリンクするために生成され、各プラットフォームで異なるディープリンク値が設定されている場合、リンクに_android_dl 。
- ディープリンクの値がiOSとAndroidで同じ場合は、_dl 。
- パススルーパラメータに追加データが渡された場合は、_p 。
ディープリンクハンドラコードサンプル
アプリには、openURLを解析し、適切に処理できるハンドラーコードが必要です。以下の例で、Singular Linkパラメータをどのようにパースするかを示します。
class DeepLinkHandler {
func handleURL(_ url: URL) {
guard let components = URLComponents(url: url, resolvingAgainstBaseURL: true) else {
return
}
var params: [String: String] = [:]
// Parse query parameters
if let queryItems = components.queryItems {
for item in queryItems {
switch item.name {
case "_dl":
params["deeplink"] = item.value
case "_ios_dl":
params["ios_deeplink"] = item.value
case "_p":
params["passthrough"] = item.value
default:
break
}
}
}
// Handle the parsed parameters
processDeepLinkParameters(params)
}
private func processDeepLinkParameters(_ params: [String: String]) {
// Process the parameters as needed
print("Processed parameters: \(params)")
}
}
// In SceneDelegate or AppDelegate
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
guard let url = URLContexts.first?.url else { return }
let handler = DeepLinkHandler()
handler.handleURL(url)
}
class DeepLinkHandler {
fun handleDeepLink(intent: Intent) {
val data: Uri? = intent.data
data?.let { uri ->
val params = mutableMapOf<String, String>()
// Parse query parameters
uri.queryParameterNames?.forEach { name ->
when (name) {
"_dl" -> params["deeplink"] = uri.getQueryParameter(name) ?: ""
"_android_dl" -> params["android_deeplink"] = uri.getQueryParameter(name) ?: ""
"_p" -> params["passthrough"] = uri.getQueryParameter(name) ?: ""
}
}
processDeepLinkParameters(params)
}
}
private fun processDeepLinkParameters(params: Map<String, String>) {
// Process the parameters as needed
println("Processed parameters: $params")
}
}
// In your Activity
class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
// Handle deep link if activity was launched from a deep link
intent?.let { DeepLinkHandler().handleDeepLink(it) }
}
override fun onNewIntent(intent: Intent?) {
super.onNewIntent(intent)
// Handle deep link if app was already running
intent?.let { DeepLinkHandler().handleDeepLink(it) }
}
}
ディファード・ディープリンクのサポート
インストール後に初めてアプリが開かれたとき、SessionをSingularに報告するときに以下のパラメータを追加して、遅延ディープリンクフローを有効にします:
- install=true
- ddl_enabled=true
Singularは、アプリが遅延ディープリンクを含むトラッキングリンクを通じてインストールされたかどうかを確認します。もしそうであれば、Session リクエストは以下の値をサーバへのレスポンスとして返します:
- deferred_deeplink - ディープリンクアドレス。これは、ユーザに正しい製品や体験を見せるために解析する必要があるものです。
- deferred_passthrough - ディープリンクに追加されたパススルーパラメータ。
クライアントアプリには、Singular SESSION APIからのレスポンスに含まれるDeferred DeeplinkおよびPassthrough Parametersを処理するコードを含め、データを適切に処理する必要があります。遅延ディープリンク値を持つSESSION通知からの応答JSONは、次のようになります:
{
"deferred_deeplink":"myapp://deferred-deeplink",
"status":"ok",
"deferred_passthrough":"passthroughvalue"
}
動的パススルーパラメータの使用
Singular トラッキングリンクは動的パススルーパラメータを含むことができます(詳細はこちら)。組織でリンクに動的パススルー パラメータを設定した場合、ディープリンクの URL には、_p パラメータに続いて URL エンコードされた JSON 文字列値または構造化されていない文字列が含まれ、適切なコンテンツまたはエクスペリエンスをユーザーに表示するために使用できます。
ショートリンクの解決
アプリが短縮されたSingularリンクから開かれる場合、openuriパラメータで送信されたopenURLがSingularロングリンクに解決されるべきであることをSingular Sessionエンドポイントに通知するために、以下のパラメータを起動リクエストに含める必要があります。
- singular_link_resolve_required=true
Singular は短縮されていないロングリンクを返し、App Developer は前述のようにリンクハンドラでディープリンクとパススルーパラメータを解析できます。
サンプルレスポンス
{
"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 のクロスデバイスソリューションを実装したり、ユーザーをデバイスレベルのセッションに関連付けたりする場合は、パラメータ custom_user_idパラメータを効果的に活用することが重要です。このパラメータには内部ユーザーIDを含める必要がありますが、個人を特定できる情報(PII)を含めないようにして、データプライバシーポリシーを遵守することが必須です。
ベストプラクティスとしては、ユーザー名、メールアドレス、またはランダムに生成された文字列からハッシュ化された値を使用することです。このアプローチを実装することで、SingularはPIIを利用できるようになります。 custom_user_idを包括的なクロスデバイスレポート、ユーザーレベルのデータエクスポート、内部BIポストバック(設定されている場合)に利用できるようになり、ユーザーのプライバシーを維持しながら分析データの粒度と価値を高めることができます。
収益のレポート
Singularはアプリを通じて得た収益に関するデータを収集し、キャンペーンのパフォーマンスとROIの分析に役立てることができます。Singularはこのデータをレポート、エクスポートログ、ポストバックで提供します。
収益イベントをトラッキングするには、すべてのイベントに使用するのと同じイベント通知エンドポイントを使用しますが、収益パラメータを含めます。
- is_revenue_event これにより、イベントは収益イベントとしてマークされます。イベント名が__iap__ 、または金額が0より大きい場合は、このパラメータを省略できます。
- purchase_receipt AndroidまたはiOSの アプリ内課金(IAP)プロセスから返されるオブジェクトです。このオブジェクトをSingularに渡すと、トランザクションの詳細がSingularに表示され、Singularのレポートがより充実したものになります。
- receipt_signature (Androidのみ)トランザクションを検証し、アプリ内詐欺に対抗するために、このデータをSingularに渡すことを強くお勧めします。
- amt これは売上金額(Double)です(例:"amt=1.99")。
- cur ISO 4217の通貨コードです(例:"cur=USD")。
GoogleのPlay Billing LibraryやAppleのStoreKitから購入オブジェクトを取得するには、Implement Subscription State Management in App Client Codeを参考にしてください。また、サブスクリプション情報を照会し、デバイス上で直接サブスクリプション状態を管理することもできます。SingularへのEventリクエストに含めるために、これらの詳細をサーバーに戻します。
カスタム収益イベントのサンプル
import requests
params = {
"a": "sdk_key_here",
"p": "Android",
"i": "com.singular.app",
"ip": "10.1.2.3",
"ve": "9.2",
"aifa": "8ecd7512-2864-440c-93f3-a3cabe62525b",
"asid": "edee92a2-7b2f-45f4-a509-840f170fc6d9",
"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": "hakfcimbkargpM",
},
"receipt_signature": "TyVJfHg8OAoW7W4wuJtasr5agEDMnNXvhfrw==",
"purchase_product_id": "com.example.product",
"purchase_transaction_id": "GPA.1234-1234-1234-12345",
}
response = requests.get("https://s2s.singular.net/api/v1/evt", params=params)
print(response.json())
GET /api/v1/evt
?a=sdk_key_here
&p=Android
&i=com.singular.app
&ip=10.1.2.3
&ve=9.2
&aifa=8ecd7512-2864-440c-93f3-a3cabe62525b
&asid=edee92a2-7b2f-45f4-a509-840f170fc6d9
&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":"hakfcimbkargpM"}
&receipt_signature=TyVJfHg8OAoW7W4wuJtasr5agEDMnNXvhfrw==
&purchase_product_id=com.example.product
&purchase_transaction_id=GPA.1234-1234-1234-12345 HTTP/1.1
Host: s2s.singular.net
Accept: application/json
curl -G "https://s2s.singular.net/api/v1/evt" \
--data-urlencode "a=sdk_key_here" \
--data-urlencode "p=Android" \
--data-urlencode "i=com.singular.app" \
--data-urlencode "ip=10.1.2.3" \
--data-urlencode "ve=9.2" \
--data-urlencode "aifa=8ecd7512-2864-440c-93f3-a3cabe62525b" \
--data-urlencode "asid=edee92a2-7b2f-45f4-a509-840f170fc6d9" \
--data-urlencode "n=RevenueEventName" \
--data-urlencode "amt=2.50" \
--data-urlencode "cur=USD" \
--data-urlencode "is_revenue_event=true" \
--data-urlencode "purchase_receipt={\"orderId\":\"GPA.1234\",\"packageName\":\"com.example\",\"productId\":\"com.example.product\",\"purchaseTime\":1417113074914,\"purchaseState\":0,\"purchaseToken\":\"hakfcimbkargpM\"}" \
--data-urlencode "receipt_signature=TyVJfHg8OAoW7W4wuJtasr5agEDMnNXvhfrw==" \
--data-urlencode "purchase_product_id=com.example.product" \
--data-urlencode "purchase_transaction_id=GPA.1234-1234-1234-12345"
アンインストールのトラッキング
Singularはデバイスのサイレントプッシュ通知を使ってアンインストールを追跡することができます。これを有効にするには、すべてのセッション通知と一緒にデバイスのプッシュトークンをSingularサーバーに送信する必要があります。
-
Singularプラットフォームとアプリでアンインストールトラッキングを設定するためのガイドに従ってください:
- iOS の場合は、APNS トークンを apns_tokenパラメータに追加します。Android の場合は、FCM トークンを fcmパラメータに追加します。
iOSのインストールレシートの取得
iOSアプリのセッションをレポートする場合、インストールレシートを install_receiptパラメータにインストールレシートを渡す必要があります。
この値を取得するには、以下のコードをアプリに追加します:
// ReceiptManager.h
@interface ReceiptManager : NSObject
+ (nullable NSString *)getInstallReceipt;
@end
// ReceiptManager.m
#import <StoreKit/StoreKit.h>
@implementation ReceiptManager
+ (nullable NSString *)getInstallReceipt {
if (@available(iOS 18.0, *)) {
dispatch_semaphore_t semaphore = dispatch_semaphore_create(0);
__block NSString *result = nil;
[SKPaymentQueue.defaultQueue addTransactionObserver:[[SKPaymentTransactionObserver alloc] init]];
if (@available(iOS 18.0, *)) {
[AppTransaction.shared fetchWithCompletionHandler:^(AppTransaction *transaction, NSError *error) {
if (error) {
NSLog(@"Failed to get app transaction: %@", error.localizedDescription);
} else {
result = transaction.jwsRepresentation;
}
dispatch_semaphore_signal(semaphore);
}];
}
dispatch_semaphore_wait(semaphore, DISPATCH_TIME_FOREVER);
return result;
} else {
NSURL *receiptURL = [[NSBundle mainBundle] appStoreReceiptURL];
if (!receiptURL) {
NSLog(@"Receipt URL not found");
return nil;
}
NSError *error = nil;
NSData *receiptData = [NSData dataWithContentsOfURL:receiptURL
options:NSDataReadingUncached
error:&error];
if (error) {
NSLog(@"Failed to read receipt: %@", error.localizedDescription);
return nil;
}
return [receiptData base64EncodedStringWithOptions:0];
}
}
@end
import Foundation
import StoreKit
class ReceiptManager {
static func getInstallReceipt() -> String? {
if #available(iOS 18.0, *) {
// Synchronous wrapper for async code
let semaphore = DispatchSemaphore(value: 0)
var result: String?
Task {
do {
let transaction = try await AppTransaction.shared
result = transaction.jwsRepresentation
semaphore.signal()
} catch {
debugPrint("Failed to get app transaction: \(error.localizedDescription)")
semaphore.signal()
}
}
semaphore.wait()
return result
} else {
// Legacy receipt fetching
guard let receiptURL = Bundle.main.appStoreReceiptURL else {
debugPrint("Receipt URL not found")
return nil
}
do {
let receiptData = try Data(contentsOf: receiptURL, options: .uncached)
return receiptData.base64EncodedString(options: [])
} catch {
debugPrint("Failed to read receipt: \(error.localizedDescription)")
return nil
}
}
}
}
データプライバシー法の遵守
Singularは、GDPRやCCPAのような消費者プライバシー法を遵守している可能性のあるパートナーと協力できるよう、プライバシー保護機能を提供しています。このようなパートナーは、エンドユーザーが個人情報を共有することに同意した場合に通知されることを望んでいます。
ユーザーに情報共有の同意を求める方法を実装している場合は、data_sharing_optionsパラメータを使ってユーザーの選択をSingularに通知します:
- ユーザが情報の共有に同意(オプトイン)した場合は"limit_data_sharing":false を渡します。
- ユーザが拒否した場合は"limit_data_sharing":true を渡します。
Singularは「ユーザープライバシーのポストバック」においてlimit_data_sharing 、関連法規を遵守するためにこの情報を必要とするパートナーに渡します。詳しくは「ユーザーのプライバシーとデータ共有の制限」をご覧ください。
注意
- data_sharing_options パラメータはオプションですが、ユーザーがオプトインしたことが特に通知された場合にのみ、パートナーがSingularと共有するアトリビューション情報があるかもしれません。