服务器到服务器 (S2S) 集成指南

注: 服务器到服务器集成仅可根据要求提供。 联系您的 Singular 客户服务经理或 Singular 支持部门。

 

Singular SDK 必须嵌入到你的应用程序中,作为Singular SDK的替代方案,Singular还提供了一个REST API,可用于构建一个从你自己的服务器运行的完整集成。

本指南介绍如何使用 Singular 构建基本的 S2S 集成,并实现各种可选功能。

有关 S2S API 端点、参数和调用示例的完整列表,请参阅《S2S 端点参考》。

基本集成

与 Singular 的最基本集成包括在有新会话时通知 Singular,换句话说,就是在应用程序打开时通知 Singular。

要通知 Singular 有关用户会话的信息,请调用会话通知端点

会话通知允许 Singular 做几件事:

  • 如果这是应用程序在特定设备上的首次会话,Singular 会识别新安装并触发安装归因流程
  • 如果会话符合重新参与会话的条件,Singular 会触发重新参与归因流程(在重新参与常见问题中了解更多信息)。
  • 否则,Singular 会将其标记为会话,用于跟踪用户活动和保留情况。

会话通知端点有一些必要参数。如需获取报告会话所需的全部数据,请参阅参考资料:检索 iOS 安装收据和参考资料:检索设备标识符和会话数据

小提示 在收集数据以报告会话时,请务必等待异步函数返回并处理各种边缘情况。 这是一个常见问题,可能导致数据丢失和部分归属。

收集和发送应用程序集 ID(Android 12+ 需要)

应用程序集 IDASID是一个新的隐私友好型 ID,用于 Android 12+ 设备。设备上由同一开发者在 Google Play 商店发布的所有应用程序都共享 App Set ID。

将应用程序集合 ID 作为参数添加到会话调用和每个事件调用中,与发送 GAID 的方式类似

要收集应用程序集 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 Appset ID 的当前范围。
          int scope = info.getScope();
  
          // 读取Android Appset ID值,它使用UUID版本4格式。
          String id = info.getId();
      }
  });

重要:发送 Google Play 安装推荐器(安卓)

安装推荐器包含有关谁将用户发送到 Google Play 商店的信息。当 Singular 可以使用安装推荐人时,它将提供最准确的安装归属方式。在第一次会话通知调用时,读取此值并将其传递给 Singular。 一些重要的 Singular 功能都需要它,例如在用户级导出(User-Level Exports)中接收 Facebook 数据、与数据目的地(Data Destinations)共享数据以及发送回帖。

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 可以是用户名、电子邮件地址、随机生成的字符串,也可以是应用程序用作用户 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()

附加归因处理

苹果搜索广告系列的归因(iOS)

Apple Search Ads 被视为自归因网络 (SAN)。 从 iOS 14.3 开始,Apple Search Ads 集成通过两个 iOS 框架提供支持

我们建议同时使用 iAd 和 AdServices 框架,直到 iAd 框架在未来被淘汰。 由于 AdServices 仍是一项新的苹果服务,Singular 将同时使用这两项服务,但在归因和报告方面,AdServices 将优先于 iAd 信号。

更多信息,请参阅我们的苹果搜索广告集成文档

通过 iAd 实施苹果搜索广告(iOS 14.2 及以下版本)

1.检索归因数据

要检索归因数据,请使用Apple Search Ads 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 之前及时接收和处理广告点击。为避免出现这种情况,苹果建议
  1. 在检索归因数据前设置几秒钟的延迟。
  2. 如果响应为 "False "或错误代码(0、2、3),则执行重试逻辑。2 秒后再次调用 Apple Attribution API。

2.将归因数据发送给 Singular

要与 Singular 共享归因数据,请使用 "事件通知"(EventNotification)端点报告保留事件名称为__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 分钟。 5 分钟后,如果调用 attributionToken(),就会生成一个新令牌。
  • 生成的标记有效期为 24 小时。

2.将归属令牌发送给 Singular

对令牌进行URL编码,并通过会话通知端点将令牌发送给Singular,同时附加&attribution_token=参数。 在每次安装和重新安装后的第一次会话中都应发送该令牌,以便Singular跟踪苹果搜索广告的下载和重新下载情况。

元安装推荐人归因(安卓)

"元推荐人 "是 Facebook 推出的安卓专用测量解决方案,允许广告商访问安卓应用程序安装的细粒度用户级归因数据(请参阅 Facebook 的数据政策)。它由实施 "Google Play 安装推荐人"(请参阅 "传递 Google 安装推荐人")和 "元安装推荐人 "技术组成,用于测量应用程序的安装情况。有关元推荐人的更多信息,请参阅常见问题。

与 Singnular 共享 Meta Install Referrer 信息

  1. 首次打开应用程序时,根据Meta 文档检索 Meta 安装 Referrer。
  2. 使用会话通知端点(Session Notification endpoint)向Singular报告会话,包括参数meta_ref。该参数为 JSON 编码,具有以下属性:

    属性 属性
    is_ct 从 Meta Install Referrer 接收到的 "is_ct "值。(例如 0 或 1)
    install_referrer 从 Meta 安装推荐器接收到的 "install_referrer "值
    actual_timestamp 从 Meta Install Referrer 接收到的 "actual_timestamp "值(如 1693978124)。

跟踪事件

Singular 可以收集应用内事件的相关数据,帮助分析营销活动的效果。事件可包括任何用户交互,从登录和注册到游戏应用中的等级提升

在实施与 Singular 的 SDK/S2S 集成之前,您应该有一份贵组织希望跟踪的事件列表(请参阅定义应用程序内事件)。

要在应用程序中发生事件时通知 Singular,请调用事件通知端点您在调用中包含的事件名称将在 Singular 报告、导出和回传中被识别。

注意

  • Singular 建议使用Singular 的标准事件和属性命名约定传递事件。 使用标准事件可简化映射,并在集成中与合作伙伴的标准事件兼容。
  • 我们强烈建议使用英文传递事件名称和其他属性,以便与第三方合作伙伴和分析解决方案兼容。
  • 事件名称限制为 32 个 ASCII 字符。对于非 ASCII 字符,转换为 UTF-8 后限制为 32 字节。
  • 事件属性和值限制为 500 个 ASCII 字符。

跟踪收入

Singular可以收集通过应用程序获得的收入数据,以帮助分析营销活动的效果和投资回报率。Singular会通过报告、日志导出和回传等方式向您提供这些数据。

要跟踪收入事件,请使用与所有事件相同的事件通知端点,但要添加以下信息:

  • is_revenue_event=true:这会将事件标记为收入事件。如果事件名称是 __iap__ 或金额大于零,可以跳过此参数。
  • 购买收据:这是从 Android 或 iOS 的应用内购买(IAP)流程返回的对象。我们强烈建议将其传递给 Singular,以便为 Singular 提供有关交易的全部详细信息,并通过数据丰富您的 Singular 报告。
  • 购买签名(仅限 Android): 我们强烈建议将此数据传递给 Singular,以验证交易并打击应用内欺诈行为。
  • 收入金额(例如,"amt=1.99")。
  • 货币(使用 ISO 4217货币代码,例如 "cur=USD")。

检索购买收据

收入事件发生后,以下是获取购买收据以便发送给 Singular 的方法:

  • 在安卓系统中:Google Play 提供了一个 API,用于获取购买收据("应用内购买数据")和购买签名("应用内数据签名")。请使用getBuyIntent()方法。
  • 在 iOS 系统中:如下例所示,使用 Apple 的应用内购买 API(更多信息,请参阅Apple 应用内购买 API)。
目标代码
// 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()

支持深度链接

深度链接是指向应用程序内特定内容的链接。当用户在安装了应用程序的设备上点击深层链接时,应用程序就会打开并显示特定的产品或体验。

奇异跟踪链接可包括深度链接和延迟深度链接(更多信息,请参阅我们的 深度链接常见问题奇异链接常见问题)。

深度链接的先决条件

对于 iOS:

针对 Android:

支持深度链接

无论何时通过深度链接打开应用程序,在向 Singular 报告会话时都要使用openuri参数添加 URL。使用 Singular 链接时需要这样做。

启用延迟深度链接

安装后首次打开应用程序时,请在向 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 短链接打开应用程序时,应在启动请求中发送以下参数,以通知 Singular 端点 openuri 中发送的 url 应解析为 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 服务器发送设备的推送令牌。

在安卓系统中跟踪卸载

要在安卓系统中启用卸载跟踪功能,首先要调用 FirebaseInstanceId.getInstance().getToken() 从应用程序中获取 FCM 令牌。如果令牌尚未生成,该方法将返回空值。有关详细信息,请参阅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 可以通过苹果的推送通知跟踪 iOS 上的卸载情况。如果你的应用程序还不支持推送通知,请参阅Apple 的指南。 一旦你的应用程序支持推送通知,在向 Singular 报告会话时,请传递从 APNS 返回的设备令牌。

注意

  • 我们假设你已经有了推送通知的实现,并从中获取了设备令牌。
  • APNS 令牌通常是本地形式的二进制数据。请按照从 APNS 收到的方式将其传递给 Singular。如果您的应用程序出于其他目的更改令牌数据类型,请确保以十六进制编码字符串的形式传递,例如: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会在"用户隐私回传"User Privacy Postbacks)中使用limit_data_sharing,并将此信息传递给需要的合作伙伴,以遵守相关规定。更多信息请参阅"用户隐私和限制数据共享"

注意

  • 该方法的使用是可选的,但可能会有归属信息,只有在明确通知用户已选择加入的情况下,合作伙伴才会与Singular共享这些信息。
  • 如果在GET请求中传递JSON对象,请记得对其进行URL编码。
字段 类型 说明 使用方法
limit_data_sharing boolean

在每个 "launch "或 "evt "请求中传递这个可选值,以显示最终用户的偏好。

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

参考:检索 iOS 安装收据

正如会话通知端点参考中所述,在报告 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 也有相关文档。为方便起见,我们提供了一些参考实现。

检索谷歌广告 ID/限制广告跟踪(安卓标识符)

在应用程序中获取广告 ID 需要使用 Google Play Services SDK。 在 AndroidManifest.xml 中添加以下标签作为应用程序元素的子元素:

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

如果您的应用程序针对 Android 12/API level 31 或更高版本,请添加访问 Google Advertising ID 的权限:

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

获取 Google 广告 ID/限制广告跟踪参数的示例代码:

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 开始,需要使用 App Tracking Transparency 来检索设备的 IDFA。如果显示 App Tracking Transparency 提示,请务必在尝试检索 IDFA 之前执行该提示和处理程序。

下面是一个示例,说明如何实现 ATT 提示(可选)以及如何检索 ATT 授权规约(必选):

Objective-C
#import <AppTrackingTransparency/ATTrackingManager.h>
  
// 如果您决定显示 ATT 提示,则可选。 显示提示并处理值。 即使多次调用也只会出现一次。 [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 之前执行该提示和处理程序。

如果不打算显示应用程序跟踪透明度,仍可检索 IDFA(值将为零)。在任何情况下都必须检索并发送 IDFV,因为如果 IDFA 不可用或全为零,Singular 就会返回 IDFV。

iOS 13 及以下版本需要使用 limit-ad-track (isAdvertisingTrackingEnabled) 标志,用于显示用户是否选择退出广告跟踪。对于 iOS 14 及以上版本,该标记已被弃用,如果被检索到,则是一个静态值。Singular 和合作伙伴将依赖较新的ATT 授权状态值来处理隐私流的数据。

以下是检索 IDFA、IDFV 和限制广告跟踪状态的示例

Objective-C Swift
// 在文件顶部导入 AdSupport 类
@import AdSupport;

获取 IDFA/限制广告跟踪参数的示例代码:

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

检索 iOS 的 Locale、Device 和 Build

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];
  }