将 SDK 添加到您的项目
将 Singular React SDK 添加到项目中:
- 在项目根目录下打开终端。
-
使用以下命令将 SDK 包下载到项目中:
npm install singular-react-native --save
- 如果你使用的是 React Native0.60+ 版本,Singular 软件包会自动链接到你的项目。
如果您使用的是 React Native0.59 或更旧的版本,请运行以下命令将 Singular 包中的本地桥接代码链接到您的项目:
react-native link singular-react-native
设置先决条件
iOS 先决条件
在项目根目录下运行以下命令:
cd ios; pod install
Android 前提条件
在 build.gradle文件中,在应用程序的 Maven 资源库中添加以下内容:
allprojects {
repositories {
maven { url 'https://maven.singular.net/' }
}
}
在应用程序的 AndroidManifest.xml文件中添加以下权限:
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<!-- 检索 Google Play Referrer 数据需要此权限。 -->
<uses-permission android:name="com.google.android.finsky.permission.BIND_GET_INSTALL_REFERRER_SERVICE" />
<!-- 从 google 许可 API 获取数据需要此权限 -->
<uses-permission android:name="com.android.vending.CHECK_LICENSE" />
如果您的应用程序是针对 Android 12/API level 31 或更高版本构建的,请添加访问 Google Advertising ID 的权限:
<uses-permission android:name="com.google.android.gms.permission.AD_ID" />
如果您已禁用 Singular SDK 的传递依赖关系,请在应用程序的 build.gradle.
implementation 'com.android.installreferrer:installreferrer:2.2'
implementation 'com.google.android.gms:play-services-appset:16.0.0'
初始化 SDK
注意:在实施 Singular SDK 时,切记要遵守业务所在地区颁布的各种隐私法,包括但不限于 GDPR、CCPA 和 COPPA。如需了解更多信息,请参阅SDK 选择加入和选择退出实践。
每次打开应用程序时,都应调用 SDK 初始化代码。它是所有Singular归因功能的前提,同时也会向Singular发送一个新的用户会话。会话用于计算用户留存率。
导入必填类
在App.js 文件中,添加以下代码导入 Singular 和 SingularConfigs 类。
import {Singular, SingularConfig, Events, Attributes} from 'singular-react-native';
配置和初始化 SDK
- 在初始化 Singular SDK 之前,你必须创建一个 SingularConfig 对象。该对象包含 SDK 密钥和 SDK 秘密(登录 Singular 账户,进入 "开发工具 > SDK 集成 > SDK 密钥 "页面即可获取)。
- 您还可以选择添加设置,以启用各种 SDK 功能。
- 支持 META 安装推荐人归属
启用"元安装推荐人 "属性所需的 SDK 配置:
- 在奇异配置对象中提供您的Facebook 应用程序 ID。
// 启用 META 安装引荐来源网址 config.withFacebookAppId("在此插入您的 FACEBOOK 应用程序 ID");
- 在奇异配置对象中提供您的Facebook 应用程序 ID。
- 然后,使用init 方法初始化 SDK,传入 SingularConfig对象
例如
const config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');
// 可选设置:
// 如果初始化时已知,则设置用户 ID
config.withCustomUserId("274e9db5c836093499df921be5b7f32001d49c50");
// 启用 META 安装推荐人
config.withFacebookAppId("INSERT YOUR FACEBOOK APP ID HERE");
// 实现深度链接
config.withSingularLinks(callBackFunction);
Singular.init(config);
Singular.init 方法 | |
---|---|
说明 | 初始化 Singular SDK。 |
使用示例 |
|
SingularConfig 选项
".with" 方法 | 说明 |
withCustomUserId(user_id) | 向 Singular 发送用户 ID(了解更多) |
withFacebookAppId(FACEBOOK_APP_ID) |
注:在 Singular 配置对象中提供您的 Facebook 应用程序 ID,以启用 META 安装推荐人属性。 |
withSingularLinks(callBackFunction) | 启用深度链接(了解更多) |
withSessionTimeoutInSec(seconds) | 修改会话超时(了解更多) |
向 Singular 发送用户 ID(可选)
您可以使用 Singular SDK 方法向 Singular 发送内部用户 ID。
注:如果使用Singular 的跨设备解决方案,则必须在所有平台上收集用户 ID。
- 用户 ID 可以是任何标识符,但不能暴露 PII(个人身份信息),例如,不能使用用户的电子邮件地址、用户名或电话号码。Singular 建议使用仅对第一方数据唯一的哈希值。
- 传递给Singular的用户ID值也应该是你在所有平台(Web/移动/PC/控制台/离线)上获取的相同的内部用户ID。
- Singular 将在用户级导出、ETL 和内部 BI 回传(如果配置)中包含用户 ID。用户 ID 是第一方数据,Singular 不会与其他方共享。
- 使用 Singular SDK 方法设置的用户 ID 值将一直存在,直到使用unsetCustomUserId 方法取消设置或卸载应用程序为止。关闭或重启应用程序不会取消设置用户 ID。
要设置用户 ID,请使用setCustomUserId 方法。要取消设置(例如,如果用户 "注销 "账户),请致电unsetCustomUserId 。
注意:如果多个用户使用一台设备,我们建议实施注销流程,为每次登录和注销设置和取消设置用户 ID。
如果已经知道应用程序打开时的用户 ID,请在初始化 Singular SDK 之前调用setCustomUserId 。这样,Singular 就能从第一次会话中获得用户 ID。不过,在用户注册或登录之前,用户 ID 通常是不可用的。在这种情况下,请在注册流程完成后调用setCustomUserId 。
Singular.setCustomUserId 方法 | |
---|---|
说明 | 向 Singular 发送用户 ID。 |
签名 | static setCustomUserId(customUserId) |
使用示例 |
|
Singular.unsetCustomUserId 方法 | |
说明 | 取消设置已发送至 Singular 的用户 ID。 |
签名 | static unsetCustomUserId() |
使用示例 |
|
重要:此高级企业功能仅在特殊情况下可用。实施前请咨询 Singular 解决方案工程师。
Singular 可以通过服务器到服务器集成接收额外的移动事件跟踪数据。要使用此功能,必须将用户 ID 映射到 Singular 的移动设备跟踪标识符。
注意:在初始化Singular SDK或获得用户ID后,请尽快调用此方法。
Singular.SetDeviceCustomUserId方法 | |
---|---|
说明 | 设置与登录相同的自定义用户 ID,并将其映射到 Singular 的跟踪标识符。 |
签名 | static setDeviceCustomUserId(customUserId) |
使用示例 |
|
处理 AppTrackingTransparency 同意
从 iOS 14.5 开始,在访问设备的 IDFA 进行追踪之前,必须先征得用户同意(使用 ATTrackingManager)。
如果想在征求用户同意前初始化 Singular SDK,可以在指定时间间隔内延迟 SDK 在没有 IDFA 的情况下触发事件,以等待用户同意。
为此,请使用waitForTrackingAuthorizationWithTimeoutInterval选项初始化 Singular SDK,如下例所示:
const config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');
// 启用 SKAdNetwork
config.withSkAdNetworkEnabled(true);
// 在发送任何事件前等待 5m 的跟踪授权
config.withWaitForTrackingAuthorizationWithTimeoutInterval(300);
Singular.init(config);
跟踪事件(非收入)
Singular 可以收集应用内事件的相关数据,帮助分析营销活动的效果并衡量关键绩效指标。例如,您的企业可能希望收集有关用户登录、注册、教程完成或游戏应用中等级提升的数据。
Singular 支持各种 标准事件,这些常用事件通常由广告网络支持,用于报告和优化。另一个优点是,当你使用标准事件名称时,Singular 会自动识别并将其添加到事件列表中,而无需手动定义。我们建议尽可能使用标准事件。
发送到 Singular 的事件列表(附带属性)应由用户体验/营销/业务团队根据企业的营销关键绩效指标编制。业务团队可参考《如何跟踪应用内事件》指南:单一归因客户指南》。
您可以为跟踪的每个事件传递各种属性,请参阅推荐的每个事件的标准属性。
在代码中,使用event或eventWithArgs方法向 Singular 发送事件。
注:对于标准事件,请使用React Native SDK 中显示的事件的React Native 名称 :标准事件和属性列表》中的 React Native 名称,如 sngLogin。
对于自定义事件,即贵组织希望测量的事件,如果与 Singular 的任何标准事件不匹配,可使用任何自定义名称(最多 32 个字符)。我们建议使用英文名称,以便与可能从 Singular 接收事件的广告网络合作伙伴兼容,达到优化目的。
Singular.event 方法 | |
---|---|
说明 | 通过事件名称向 Singular 报告用户事件。 |
使用示例 |
|
Singular.eventWithArgs方法 | |
方法描述 | 向 Singular 报告用户事件,以地图/对象的形式传递事件名称和其他信息。 |
使用示例 |
|
跟踪收入
Singular 可以收集通过应用程序获得的收入数据,以帮助分析营销活动的绩效和投资回报率。Singular 将通过报告、日志导出和回传等方式向您提供这些数据。
在向 Singular 报告收入事件时,我们建议传递从 Android 或 iOS 的应用内购买(IAP)流程返回的购买对象。这样,Singular 就能获得交易的所有详细信息,从而丰富 Singular 报告的数据。此外,Singular 还能从谷歌获得交易收据,用于在打击应用内欺诈时验证交易。
在 React Native 中传递购买对象
这种方法需要使用React Native 的应用内购买包来管理应用程序中的交易。
Singular.inAppPurchase 方法 | |
---|---|
说明 | 向 Singular 报告 IAP 事件。 |
使用示例 |
|
注意:以三个字母的 ISO 4217 货币代码形式传递货币,例如"USD," "EUR", "INR" 。
使用本地代码传递购买对象
如果不使用 React Native 应用内购买软件包,仍然可以通过购买对象向 Singular 发送收入事件,但必须使用 iOS 和 Android 本机代码。
注意:以三个字母的 ISO 4217 货币代码传递货币,例如"USD," "EUR", "INR"。
iOS
iapComplete:transaction 方法 | |
---|---|
说明 | 向 Singular 报告 IAP 事件及所有详细信息,可选择添加事件名称。 |
使用示例 |
|
安卓
要利用 Android 的 IAP 功能,首先要在应用程序的 build.gradle文件中:
implementation 'com.singular.sdk:singular_sdk:9.+
Singular.revenue 方法 | |
---|---|
说明 | 使用从 Google Billing Library 接收到的购买对象向 Singular 报告收入事件。 |
使用示例 |
|
Singular.customRevenue 方法 | |
说明 | 向 Singular 报告收入事件,并自定义事件名称和从谷歌账单库接收的购买对象。 |
使用示例 |
|
不使用购买对象报告收入事件
虽然我们强烈建议按上述方式报告收入事件,但您也可以只通过传递货币和交易金额向 Singular 发送收入事件。请注意,Singular 不会获得购买收据,也无法验证交易。
Singular.revenue 方法 | |
---|---|
说明 | 向 Singular 报告收入事件,包括收入货币和金额。 |
使用示例 |
|
Singular.customRevenue方法 | |
说明 | 向 Singular 报告收入事件,包括收入货币和金额以及事件的自定义名称。 |
使用示例 |
|
注意:传递货币为三个字母的 ISO 4217 货币代码,例如"USD," "EUR", "INR" 。
添加广告收入归属支持(高级)
Singular与谷歌AdMob、AppLovin、Unity LevelPlay (IronSource)和TradPlus等中介平台集成,用于广告收入归属。通过我们的通用广告收入 SDK 集成,Singular 还支持其他中介平台。
您可以通过在 Singular SDK 集成中添加代码片段,从您的中介平台获取广告收入归因数据。这也允许您获取 SKAdNetwork 广告系列的广告收入数据。
从您的中介平台获取用户级广告收入后,Singular 就能将归属广告收入发送回媒体来源,这些媒体来源可以接受这些数据来开展 AdROAS 营销活动。
请参阅 SDK 实施说明和代码片段 [这里].
混合事件跟踪(高级)
Singular 建议通过集成到应用程序中的 Singular SDK 发送所有事件和收入。不过,Singular 也可以从其他来源收集事件和收入。
任何非通过 Singular SDK 发送的事件都必须符合 Singular 的服务器到服务器事件文档要求,并提供匹配的设备标识符以正确归属事件。
重要:
如果服务器到服务器事件请求中使用的设备标识符在 Singular 中没有匹配的设备标识符,就会出现差异。请注意以下可能性:
- 如果事件请求是在 Singular SDK 从应用程序会话记录设备标识符之前收到的,那么该事件请求将被视为未知设备的 "第一次会话",Singular 将把该设备作为有机归属。
- 如果 Singular SDK 确实记录了设备标识符,但 Singular SDK 标识符与服务器到服务器事件请求中指定的设备标识符不同,那么事件将被错误归属。
混合事件跟踪指南
Singular可以收集来自服务器的收入数据,帮助分析营销活动的表现和投资回报率。
要求:
- 从应用内注册或登录事件中捕获并传递设备标识符,并将此数据与服务器上的用户 ID 一起存储。由于用户的设备标识符可能会发生变化,因此请确保在用户生成应用程序会话时更新标识符。这将确保服务器端事件归属于正确的设备。
- 服务器端事件是平台特定的,只能使用与设备平台相匹配的设备标识符发送(如 iOS 设备的 IDFA 或 IDFV)。
- 您可以使用 Singular 内部 BI 回传机制将事件实时推送到内部端点,以便更新服务器端的数据集。请参阅内部 BI 回传常见问题。
- 查看服务器到服务器集成指南中的"跟踪收入 "部分,了解详情。
请点击以下链接了解如何启用这些合作伙伴。
添加深度链接支持
深层链接是指向应用程序内部特定内容的链接。当用户在安装了应用程序的设备上点击深层链接时,应用程序就会打开并显示特定的产品或体验。
奇异跟踪链接可以包括深度链接和延迟深度链接(更多信息请参阅我们的 深度链接常见问题和奇异链接常见问题)。
下面的说明将告诉您如何
- 访问导致您的应用程序被打开的跟踪链接、
- 读取深度链接目的地,以及
- 显示相应内容。
注: 本文假设您的组织正在使用Singular Links(Singular 2019 年推出的新追踪链接技术)。
请参阅生成链接 [传统跟踪链接]。
启用 Singular 链接
要在 iOS 和 Android 中启用 Singular Links,请参阅Singular Links Prerequisites。
处理奇异链接
Singular SDK 提供了一种处理机制,用于读取导致应用程序被打开的跟踪链接的详细信息。
要使用处理程序,请
- 在创建 withSingularLinks创建 SingularConfig 对象。这将注册一个 Singular Links 处理程序。
- 在处理程序中,调用或定义一个接收 SingularLinksParams 对象的回调函数,如下例所示。SingularLinksParams 对象包含以下字段:
- deeplink- 在 _dl这是您需要解析的内容,以便向用户显示正确的产品或体验。
- passthrough- 包含在 _p查询参数中包含的所有参数。
- isDeferred- 如果是延迟的深度链接,则为 true。
-
urlParameters- 奇异跟踪链接的所有查询字符串参数。
- 您必须将 _forward_params=1 键/值对附加到奇异跟踪链接,以便 SDK 提供所有查询字符串参数。
const config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');
config.withSingularLink(singularLinksParams => {
const deeplink = singularLinksParams.deeplink;
const passthrough = singularLinksParams.passthrough;
const isDeferred = singularLinksParams.isDeferred;
const urlParameters = singularLinksParams.urlParameters;
// 在此处添加代码以处理深层链接
});
//...
Singular.init(config);
设置先决条件
iOS 先决条件
在项目的 AppDelegate.m中添加以下内容:
// AppDelegate.m 顶部
#import <Singular-React-Native/SingularBridge.h>
- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// 在 didFinishLaunchingWithOptions 内添加
[SingularBridge startSessionWithLaunchOptions:launchOptions];
return YES;
}
// 将此方法添加到应用程序委托中
- (BOOL)application:(UIApplication *)application
continueUserActivity:(NSUserActivity *)userActivity
restorationHandler:(void (^)(NSArray<id> * _Nullable))restorationHandler{
[SingularBridge startSessionWithUserActivity:userActivity];
return YES;
}
Android 前提条件
在项目的 MainActivity.java中,添加以下内容:
// 作为导入的一部分添加在类的顶部
import android.content.Intent;
import net.singular.react_native.SingularBridgeModule;
// 添加到 MainActivity 类
@Override
public void onNewIntent(Intent intent) {
if(intent.getData() != null) {
setIntent(intent);
super.onNewIntent(intent);
SingularBridgeModule.onNewIntent(intent);
}
}
简介:SKAdNetwork 和 SKAN
SKAdNetwork是苹果公司在不损害最终用户隐私的前提下,为移动安装提供属性的新框架。Singular 的新版 iOS SDK 可帮助您以最小的工程投入无缝实施 SKAdNetwork。该SKAdNetwork实施基于SKAN--Singular为顺利实施SKAdNetwork而开发的标准。
有关 Singular SKAdNetwork 实施的完整指南,请参阅iOS SDK SKAdNetwork 实施指南。
启用 SKAdNetwork 跟踪
要为应用程序启用 SKAdNetwork 跟踪功能,请在初始化 Singular 之前打开 skAdNetworkEnabled 配置选项:
const config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');
// 启用 SKAdNetwork
config.withSkAdNetworkEnabled(true);
// 在转换值更新时注册回调函数
config.conversionValueUpdatedHandler(value => {
console.log(`Updated conversion value: ${value}`);
});
Singular.init(config);
处理转换值更新
托管模式
默认情况下,SKAdNetwork 实现直接从 Singular 服务器端管理转换值。
这样可以最大限度地提高灵活性,因为您可以通过 Singular 平台设置和更改转换值,而无需修改客户端代码。
这种服务器端管理模式还有助于您处理SKAdNetwork 定时器。SKAdNetwork 允许您在注册 SKAdNetwork 后 24 小时内更新转换值。任何更新转换值的调用都会将计时器延长 24 小时。因此,在选择转换事件时,您必须确保事件在该更新窗口内发生。在托管模式下,您可以随时更改转换事件配置,而无需发布应用程序的新版本。
手动模式
如果您想在应用程序代码中自行更新转换值,请在初始化 SDK 时调用withManualSkanConversionManagement:
const config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');
// 启用 SKAdNetwork
config.withSkAdNetworkEnabled(true);
// 启用手动转换值更新
config.withManualSkanConversionManagement();
Singular.init(config);
然后,在应用程序生命周期中需要更新转换值的地方使用skanUpdateConversionValue方法:
skanUpdateConversionValue 方法 (JavaScript) | |
---|---|
说明 | 手动更新 SKAdNetwork 转换值。 |
签名 | Singular.skanUpdateConversionValue(conversionValue) |
使用示例 |
|
注意: 如果未将 SDK 设置为初始化时手动更新,则skanUpdateConversionValue方法将不起作用。
检索转换值
要获取当前转换值,请使用skanGetConversionValue方法。该方法在托管模式和手动模式下均有效。
skanGetConversionValue 方法(JavaScript) | |
---|---|
说明 | 获取由 Singular SDK 跟踪的当前转换值。 |
签名 | Singular.skanGetConversionValue() |
使用示例 |
|
创建短链接
注:此功能在 SDK 3.1.8+ 版本中可用。
使用短链接可将冗长、充满参数的 Singular 链接转换为更短、更安全的链接,方便共享。
通常情况下,您需要动态创建短链接,以便应用程序的用户可以与朋友分享,邀请他们使用应用程序。
要创建短链接,您需要
使用createReferrerShortLink方法创建短链接,如下例所示。
Singular.createReferrerShortLink (
"https://sample.sng.link/B4tbm/v8fp?_dl=https%3A%2F%2Fabc.com",
"John Doe", // 推荐人姓名
"aq239897", // 推荐人 ID
{"channel": "sms"}, // 要添加到链接中的任何参数
(shortLinkURL,error) => {
/* 如果 shortLinkURL 不为空,则在此处添加共享逻辑。如果出现错误,则根据错误原因添加重试/尝试/修改传递给函数的参数的逻辑。 */
}
)
跟踪卸载
要让 Singular 跟踪应用程序的卸载情况:
- 首先,在Singular平台中配置应用程序,详见设置卸载跟踪 [Android][iOS]。
- 使用首选方法在 React Native 中检索APNS/FCM令牌。
- 调用setUninstallToken方法,像下面的示例一样传递 APNS/FCM 令牌。请确保根据设备平台传递正确的令牌。
Singular.setUninstallToken 方法 | |
---|---|
说明 | 向 Singular 发送 APNS/FCM 令牌,以便其跟踪应用程序卸载情况。 |
使用示例 |
|
修改会话超时
Singular SDK 会自动管理用户会话,因此你不需要添加任何代码来处理会话。不过,您可以根据需要修改会话超时值。
默认情况下,如果应用程序在后台运行 60 秒或更长时间后才返回前台,SDK 就会注册一个新会话。
要更改超时值,请在创建 SingularConfig 对象时使用.withSessionTimeoutInSec。例如
const config = new SingularConfig('<SDK KEY>', '<SDK SECRET>')
.withSessionTimeoutInSec(120); // 将超时设置为 120 秒
Singular.init(config);
遵守数据隐私法
Singular提供隐私保护功能,帮助您与任何可能遵守消费者隐私法(如GDPR和CCPA(加州消费者隐私法))的合作伙伴合作。 这些合作伙伴希望在最终用户同意共享其私人信息时得到通知。
限制数据共享
如果你已经实施了一种征求用户同意共享其信息的方法,请使用limitDataSharing方法通知 Singular 用户的选择:
- 使用limitDataSharing:NO表示用户同意(选择加入)共享其信息。
- 如果用户不同意,则使用 limitDataSharing:YES。
Singular在"用户隐私回传"中使用限制数据分享,并将此信息传递给需要的合作伙伴,以遵守相关法规。更多信息请参阅"用户隐私和限制数据共享"。
注意:该方法的使用是可选的,但可能会有归属信息,只有在明确通知用户已选择的情况下,合作伙伴才会与Singular共享这些信息。
Singular.limitDataSharing方法 | |
---|---|
签名 | Singular.limitDataSharing(shouldLimitDataSharing) |
说明 | 通知 Singular 用户同意(选择加入)共享私人数据。限制数据共享方法可让您选择控制应用程序是否向第三方发送用户数据。如果您想根据用户偏好或隐私要求限制数据共享,这将非常有用。 |
使用示例 |
|
遵守 GDPR 的其他方法
Singular SDK 提供了多种方法,帮助您遵守 GDPR 政策,并让 Singular 了解用户是否同意追踪。
Singular.trackingOptIn 方法 | |
---|---|
说明 | 通知 Singular 用户同意(选择加入)跟踪。TrackingOptIn()方法用于向Singular服务器发送 “gdpr ”事件。如果您不调用此方法,应用程序将继续跟踪用户,就像他们已经同意一样,但不会特别将他们标记为 GDPR 选择加入。如果您的应用程序需要遵守 GDPR(《通用数据保护条例》),则应调用此功能,以确保正确记录用户同意。 |
使用示例 |
|
Singular.stopAllTracking 方法 | |
说明 |
停止此用户在此应用程序上的所有跟踪活动。 重要: 这将有效禁用 Singular SDK,即使在重启应用程序后也是如此。重新启用 SDK 的唯一方法是调用 resumeAllTracking。 |
使用示例 |
|
Singular.resumeAllTracking 方法 | |
说明 | 恢复跟踪此用户在此应用程序上的活动。 |
使用示例 |
|
Singular.isAllTrackingStopped 方法 | |
说明 | 检查此用户在此应用程序上的跟踪状态。如果跟踪已停止,则返回 true。 |
使用示例 |
|