开始之前：SDK 先决条件

• 按照集成 Singular SDK中的步骤操作：规划和先决条件》中的步骤。
  这些步骤是任何 Singular SDK 集成的先决条件。
• 验证您是否使用Google EDM4U，即用于 Unity 的 Google 外部依赖关系管理器。
  什么是 Google EDM4U？了解更多 [此处]。

1.安装 SDK

1.1.下载和导入 SDK 软件包

1.2.为 Android 配置

-keep class com.singular.sdk.** { *; }
-keep public class com.android.installreferrer.** { *; }
-keep public class com.singular.unitybridge.** { *; }

1.3.iOS 提示

pod repo update
pod update

// Printing Identifier for Vendor (IDFV) to Xcode Console for use in Singular SDK Console


NSLog(@"Singular === IDFV: %@", [[[UIDevice currentDevice] identifierForVendor] UUIDString]);

2.SDK 集成

2.1.创建SingularSDKObject

将SingularSDKObject添加到层次结构中

配置 SingularSDKObject 设置

1. 在SingularSDKObject 的 "检查 "窗格中，将 Singular SDK 密钥和 SDK 秘密粘贴到相应字段。要获取 SDK 密钥和秘钥，请登录您的 Singular 账户，进入"开发工具 > SDK 集成 > SDK 密钥"（Developer Tools > SDK Integration > SDK Keys）。
   
   
   
   重要：请勿使用 Singular 报告 API 密钥，否则将无法收到 SDK 数据。请按照上述说明获取正确的密钥和秘钥。
   
   
   

   如果 Singular SDK 密钥和秘密应用错误，数据将无法发送到 Singular。
   使用 Singular SDK 控制台测试您的实现，以验证行为是否正确。

   注： SingularSDKObject 的默认检查窗格设置：

   检查窗格中启用了以下选项：

   #

   • 唤醒时初始化（选中）

     此设置可使 Unity 根据应用程序的唤醒状态控制 Singular SDK 初始化。

     请根据您的应用程序要求遵循隐私合规性，并根据需要更新此选项。取消选中该选项将禁止在唤醒状态下初始化 Singular SDK，并需要手动初始化。

   • 已启用 SKAN（选中）

     从 Unity SDK 4.0.17 版开始， 默认启用SKAdNetwork。 在托管模式（Singular 使用您在 Singular 面板中选择的转换模型为您更新 SKAN 转换值）下启用。

   • 等待跟踪授权，设置为 0（关闭）

     如果您的应用程序显示 "应用程序跟踪透明度（ATT）"提示，建议将此超时设置为 300 秒。添加超时会延迟 Singular SDK 会话，允许用户在将事件记录到 Singular 服务器之前授权/拒绝 AppTrackingTransparency 同意。一旦用户回复 ATT 提示，Singular SDK 就会继续，不会有任何延迟。这样就可以在用户同意时捕获 IDFA 标识符，以便进行安装归属。如果不显示 ATT，则该选项的默认值应保持为 0（不等待）。

   • 启用日志记录（选中）

     启用 Singular SDK 的日志记录功能。它必须与"日志级别"选项一起使用。
     "日志级别 "应使用 "int "数字指定，如下面的枚举映射所示。在此范围内，数字越小，日志就越详细。

     //Based on Android Logger.java log levels enum: android.util.Log
     public enum LogLevel {
        Verbose = 2,
        Debug   = 3,
        Info    = 4,
        Warn    = 5,
        Error   = 6,
        Assert  = 7
        }

     注意： 目前，大多数日志只适用于 Android 系统。

   • Ddl 超时秒数设置为 0

     默认情况下，设置为 "0 "时，超时时间为 60 秒。这将告诉 Singular 服务器搜索与上次触摸属性相关联的深度链接值的时间。如果找到了延迟的深度链接，它会在 SDK 会话请求的响应中发送回应用程序，并在 SingularLinkHandler 中进行处理。如果在 60 秒内没有找到递延深度链接，服务器就会停止搜索。

   • 会话超时秒数设置为 0

     这是应用程序从后台返回前台时，Singular SDK 注册新会话前的超时时间（以秒为单位）。默认情况下，设置为 "0 "时，超时时间为 60 秒。如有需要，您可以调整此设置以获得更大的窗口。

   • 短链接解决超时设置为 0

     默认情况下，设置为 "0 "将使用 10 秒超时。该超时可保护用户体验。如果给定的短链接在指定时间内未解决，则 Singular SDK 不会触发深度链接处理程序。

   其他检查窗格选项：

   启用 Facebook（META 安装推荐人）

   #

   要支持 META 安装推荐人归属方法，请将您的 Facebook 应用程序 ID 添加到 SingularSDKObject 的检测窗格中。

   1. 单击主场景中的 SingularSDKObject。
   2. 打开 "检查窗格"，找到 "Facebook 应用 ID "字段。
   3. 添加 Facebook 应用程序 ID

   什么是 Meta Install Referrer？

   在哪里可以找到应用程序的 Facebook 应用程序 ID？

2.2.使用 SKAdNetwork

从 Unity SDK 4.0.17 版开始， SKAdNetwork默认启用。 它在 "托管模式"（Singular 使用您在 Singular 面板中选择的转换模型为您更新 SKAN 转换值）中启用。

要使用 SKAdNetwork，只要您使用的是最新的 SDK，就不需要设置任何其他内容或添加任何代码。

其他信息

// A sign-up event happened


Singular.Event("SignUp");

// Update the conversion value to 7


SingularSDK.SkanUpdateConversionValue(7);

int? value = SingularSDK.SkanGetConversionValue();

public class Main : MonoBehaviour, SingularConversionValueUpdatedHandler {
  void Awake() {
    SingularSDK.SetConversionValueUpdatedHandler(this);
  }

  void OnConversionValueUpdated(int value) {
    // Use the conversion value


  }
}

2.3.处理 iOS 应用程序跟踪透明度（ATT）同意书

您是否显示了应用程序跟踪透明度（ATT）提示？

从 iOS 14.5 开始，应用程序在访问和共享某些用户数据（包括设备的 IDFA）之前，必须征得用户同意（使用应用程序跟踪透明度框架），这有助于实现跟踪目的。

Singular 和广告网络从 IDFA 中获益匪浅，可以识别设备并执行安装归因（不过也有不使用 IDFA 的方法）。我们强烈建议在 征得用户同意后获取 IDFA。

建议延迟 Singular SDK 初始化，直到用户回复 ATT 提示。

默认情况下，Singular SDK 会在初始化时发送用户会话。当会话从新设备发送时，会立即触发 Singular 的归属过程--该过程仅根据 Singular 当时可用的数据执行。因此，在Singular SDK 发送第一个会话之前征求同意和检索 IDFA 至关重要。

要配置waitForTrackingAuthorizationWithTimeoutInterval，请调整SingularSDKObject 检测窗格中的配置选项。这将设置 Singular SDK 在将事件记录到 Singular 服务器之前等待用户授权/拒绝 AppTrackingTransparency 同意的最长时间（以秒为单位）。

2.4.处理深层链接

深层链接是引导用户访问应用程序中特定内容的 URL。当用户在已安装应用程序的设备上点击深层链接时，应用程序会打开并显示特定产品或体验。

单个跟踪链接可以包含深度链接和延迟深度链接。有关详细信息，请参阅我们的深度链接常见问题和奇异链接常见问题。

展开以下章节了解平台支持和处理程序代码的详细信息：

using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using Singular;

public class SingularMain : MonoBehaviour, SingularLinkHandler
{
    // Start is called before the first frame update


    void Start()
    {
        
    }
    
    void Awake () {
        Debug.Log("Singular === Awake");
        /* Register the class as the Singular Link handler. 
           You can call this method at any point in the app's run. 
           It will fetch the tracking link details and call OnSingularLnkResolved. */
        SingularSDK.SetSingularLinkHandler(this);
    }
    
    public void OnSingularLinkResolved(SingularLinkParams linkParams) {
        Debug.Log("Singular === OnSingularLinkResolved");
        
        // The deep link destination, as configured in the Manage Links page


        string deeplink = linkParams.Deeplink;

        // The passthrough parameters added to the link, if any.


        string passthrough = linkParams.Passthrough;

        // Whether the link configured as a deferred deep link.


        bool isLinkDeferred = linkParams.IsDeferred;

        // Add code here to process the deeplink


        Debug.Log("Singular === deeplink: "+deeplink);
        Debug.Log("Singular === passthrough: "+passthrough);
        Debug.Log("Singular === isLinkDeferred: "+isLinkDeferred);      
    }
}

public void SetSingularLinkHandler(SingularLinkHandler 
handler)

public class Main : MonoBehaviour, SingularLinkHandler {
    void Awake () {
        SingularSDK.SetSingularLinkHandler(this)
    }
}

public void OnSingularLinkResolved(SingularLinkParams
linkParams)

public void OnSingularLinkResolved(SingularLinkParams
linkParams){
    // Read the tracking link details and log them


    Debug.Log("deeplink: " + linkParams.Deeplink);
    Debug.Log("passthrough: " + linkParams.Passthrough);
    Debug.Log("is_deferred: " + linkParams.IsDeferred);
}

2.5.初始化 SDK

每次打开应用程序时都应调用 SDK 初始化代码。它是所有Singular归因功能的前提，并向Singular发送一个新会话，用于计算用户留存。

默认情况下，当通过 Awake 方法创建场景时，SingularSDK.cs会自动初始化 SDK。

手动初始化

如果您希望在应用程序运行的稍后阶段手动初始化 SDK，请执行以下操作：

1. 在 SingularSDK 对象的检查窗格中禁用 "唤醒时初始化"选项。
2. 使用SingularSDK.InitializeSingularSDK静态方法初始化 SDK：

public void InitializeSingularSDK()

// SDK Key and SDK Secret are set on the 


// game object associated with SingularSDK 


SingularSDK.InitializeSingularSDK();

2.6.配置会话超时（可选）

默认情况下，如果应用程序在后台运行 60 秒或更长时间后才返回前台，Singular SDK 就会注册一个新的会话。您可以通过修改 SingularSDKObject 的会话超时Sec属性来更改默认超时值。

2.7.向 Singular 发送用户 ID（可选）

你可以使用Singular SDK方法向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，请在初始化 Singular SDK 之前调用SetCustomUserId 。这样，Singular 就能从第一次会话中获取用户 ID。不过，在用户注册或登录之前，用户 ID 通常是不可用的。在这种情况下，请在注册流程完成后调用SetCustomUserId 。

SingularSDK.SetCustomUserId("custom_user_id");

SingularSDK.UnsetCustomUserId();

SingularSDK.SetDeviceCustomUserId('CustomUserId');

3.跟踪事件和收入

3.1.跟踪事件（非收入）

Singular 可以收集有关应用程序内事件的数据，帮助分析营销活动的效果并衡量关键绩效指标。例如，您的企业可能希望收集有关用户登录、注册、教程完成或游戏应用中等级提升的数据。

Singular 支持各种 标准事件。广告网络通常支持这些常用事件，用于报告和优化。另一个优点是，当您使用标准事件名称时，Singular 会自动识别并将其添加到事件列表中，而无需手动定义。我们建议尽可能使用标准事件。

发送到 Singular 的事件列表（附带属性）应由用户体验/营销/业务团队根据企业的营销关键绩效指标编制。业务团队可以参考《如何跟踪应用内事件：单一归因客户指南》。

您跟踪的每个事件都可以传递各种属性。请参阅推荐的每个事件的标准属性。

使用代码中的 event 或 eventWithArgs 方法向 Singular 发送标准事件。

SingularSDK.Event(Events.sngLogin);

public static void Event(string name)

public static void Event(string name, params object[] args)

public static void Event(Dictionary<string, object> args, string name)

// 1) Send the standard event Login


SingularSDK.Event(Events.sngLogin);

// 2) An example custom event passing two key value pairs


SingularSDK.Event("myEventName", "Key1", "Value1", "Key2", 1234);

// 3) An example JSON Event passing a dictionary


// Create a dictionary for attributes


Dictionary<string, object> attributes = new Dictionary<string, object>();

// Add attributes


attributes["key1"] = "value1";
attributes["key2"] = "value2";
attributes["key3"] = "value3";
// Add more attributes as needed



SingularSDK.Event(attributes, "myEventName");

3.2.跟踪收入

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

您可以使用Unity 内置的 IAP（应用内购买）对象跟踪收入事件。通过这种方式，Singular 可以获得有关购买的所有可用信息，从而提供更丰富的报告。Singular 还会获得购买收据，Singular 会在后端使用该收据验证购买行为并排除归因欺诈。

public static void InAppPurchase(Product product, Dictionary<string, object> attributes, bool isRestored = false)

public static void InAppPurchase(string eventName, Product product, Dictionary<string, object> attributes, bool isRestored = false)

public static void InAppPurchase(IEnumerable<Product> products,
Dictionary<string, object> attributes, bool isRestored = false)

public static void InAppPurchase(string eventName,IEnumerable<Product> products, Dictionary<string, object> attributes, bool isRestored = false)

// IAP with a single product and no extra attributes


SingularSDK.InAppPurchase(myProduct, null);

// IAP with a single product and attributes


var attr = new Dictionary<string, object>() {
["my_first_attribute"] = "value1",
["my_second_attribute"] = "value2"};
 
SingularSDK.InAppPurchase(myProduct, attr);

// IAP with with a single product, 


// no extra attributes and a custom event name



SingularSDK.InAppPurchase("MyCustomProduct",
myProduct, null);

// IAP with list of products, no extra attributes


SingularSDK.InAppPurchase(myProductList, null);

// IAP with with list of products, no extra attributes


// and a custom event name



SingularSDK.InAppPurchase("MyCustomProducts",
myProductList, null);

public static void Revenue(string currency, double amount)

public static void Revenue(string currency, double amount, string productSKU, string productName, string productCategory, int productQuantity, double productPrice)

public static void Revenue(string currency, double amount, Dictionary<string, object> attributes)

// Send a revenue event with no product details


SingularSDK.Revenue("USD", 1.99);

// Send a revenue event with product details


SingularSDK.Revenue("USD", 4.99, "coin_package_abc123", "Coin Pack 5", "Bundles", 1, 4.99);

// Send a revenue event with JSON Dictionary for attributes


Dictionary<string, object> attributes = new Dictionary<string, object>();

// Add attributes


attributes["productSKU"] = "coin_package_abc123";
attributes["productName"] = "Coin Pack 5";
attributes["productCategory"] = "Bundles";
attributes["productQuantity"] = 2;
attributes["productPrice"] = 4.99;

SingularSDK.Revenue("USD", 9.98, attributes);

public static void CustomRevenue(string eventName, string currency, double amount)

public static void CustomRevenue(string eventName, string currency, double amount, string productSKU, string productName, string productCategory, int productQuantity, double productPrice)

public static void CustomRevenue(string eventName, string currency, double amount, Dictionary<string, object> attributes)

// Send a revenue event with a custom name


SingularSDK.CustomRevenue("MyCustomRevenue", "USD", 9.99);

// Send a revenue event with a custom name + product details


SingularSDK.CustomRevenue("MyCustomRevenue", "USD", 50.50, "abc123", "myProductName", "myProductCategory", 2, 25.50);

// Send a revenue event with a custom name + JSON Dictionary for attributes


// Create a dictionary for attributes


Dictionary<string, object> attributes = new Dictionary<string, object>();

// Add attributes


attributes["productSKU"] = "coin_package_abc123";
attributes["productName"] = "Coin Pack 5";
attributes["productCategory"] = "Bundles";
attributes["productQuantity"] = 2;
attributes["productPrice"] = 4.99;
// Add more attributes as needed



SingularSDK.CustomRevenue("MyCustomRevenue", "USD", 9.98, attributes);

3.3.混合事件跟踪（高级）

Singular 建议通过集成到应用程序中的 Singular SDK 发送所有事件和收入。但是，Singular 也可以从其他来源收集事件和收入。

任何未从 Singular SDK 发送的事件都必须符合 Singular 的服务器到服务器事件文档要求，并提供匹配的设备标识符，以便正确归属事件。

混合事件跟踪指南

4.高级选项

4.1.创建短推荐人链接

使用短链接可将冗长、充满参数的奇异链接转换为更短、更安全的链接，方便分享。

通常情况下，您需要动态创建短链接，以便应用程序的用户可以与朋友分享，邀请他们使用应用程序。

要创建短链接，您需要

• 指向应用下载的奇异链接（请参阅奇异链接常见问题）。
• 您可以为链接动态添加任何参数（选项列表请参阅跟踪链接参数）。
• 如果要跟踪新应用的安装情况，返回到共享链接的用户，则必须提供推荐用户的推荐人名称和推荐人 ID。

使用createReferrerShortLink方法创建短链接，如下例所示。

void callback(string shortLinkURL, string error){
    // Add your share logic here if shortLinkURL is not null


    // If there was an error, add logic to retry/abort/modify the params


    // passed to the function, based on the cause of the error


}

SingularSDK.createReferrerShortLink(
    "https://sample.sng.link/B4tbm/v8fp?_dl=https%3A%2F%2Fabc.com",
    "John Doe", // Referrer Name


    "342", // Referrer ID


    new Dictionary<string, string>() { 
        // a Dictionary object containing any parameters you want to add


        {"channel", "sms"}
    },
    callback 
);

4.2.添加广告收入归属支持

4.3.跟踪卸载

安卓卸载跟踪

要启用安卓应用程序的卸载跟踪功能，请首先在 Singular 平台上配置应用程序，详情请参阅《 设置卸载跟踪》。然后，按照以下说明操作。

使用 Firebase Cloud Messaging (FCM) 启用卸载跟踪：

1.与 FCM 集成：

要跟踪卸载，您可以使用 Firebase Cloud Messaging (FCM) 平台的服务。如果您尚未使用 FCM，请按照 Google 的说明 在 Android 上设置 Firebase Cloud Messaging 客户端应用程序。

2.更新 AndroidManifest.xml 文件：

更新 AndroidManifest.xml 文件，为应用程序添加必要的意图过滤器（用实现 Firebase 服务的类替换 MyFirebaseMessagingService）：

<service android:name=".java.MyFirebaseMessagingService" android:exported="false">
  <intent-filter>
    <action android:name="com.google.firebase.MESSAGING_EVENT" />
  </intent-filter> 
</service>

3.注册并发送 FCM 设备令牌：

获取 FCM 令牌后，将其作为参数传递给 "RegisterTokenForUninstall "方法：

SingularSDK.RegisterTokenForUninstall(String fcmDeviceToken);

RegisterTokenForUninstall "方法应在 "SingularSDK.InitializeSingularSDK() "方法之前调用。

iOS 卸载跟踪

iOS 上的卸载跟踪基于苹果的推送通知技术。如果您的应用程序不支持推送通知，请参阅 Apple 指南。如果您的应用程序已经支持推送通知，则必须在 SDK 初始化后使用 RegisterTokenForUninstall 方法传递从 APNS 返回的设备令牌。

public static void RegisterTokenForUninstall
(string APNSToken)

// pass the APNS token as a hex-string 


  SingularSDK.RegisterTokenForUninstall("ba85ab31a7c7
f5c2f012587f29fb0e596d4b67e7b7b2838fa1a8582c1f7dbdee");

4.4.添加全局属性

对于应用程序发送的每个会话和事件，Singular SDK 都允许你定义自定义的附加属性发送给 Singular 服务器。 这些属性可以代表有关用户、应用程序模式、状态或其他任何信息。一旦设置了这些属性，它们就可以作为报告中的维度，您可以用它们来细分数据。

例如，如果您有一个游戏应用程序，您可以定义一个名为 "级别 "的属性，并将其初始设置为 "0"。应用程序发送的任何会话和事件都将带有 "Level"："0".一旦用户等级提升，您就可以将该属性重置为 "1"，以此类推。然后，您就可以获得按用户等级分列的报告，包括会话、事件计数和收入数据。

在初始化前设置全局属性

在初始化SDK之前，你可以使用SetGlobalProperty 方法通过SingularSDK设置全局属性。如果希望会话中包含全局属性，请关闭 "唤醒时初始化 "标记。

由于全局属性及其值会在应用程序运行期间持续存在，因此您要设置的属性可能已经被设置为不同的值。使用overrideExisting参数可告诉 SDK 是否用新值覆盖现有属性。

初始化后设置全局属性

在应用程序运行期间，您可以随时使用以下方法设置、取消设置和检索全局属性。

bool result = SingularSDK.SetGlobalProperty("key", "value", false);

Dictionary<string, string> props = SingularSDK.GetGlobalProperties();

SingularSDK.UnsetGlobalProperty(“test_key”);

SingularSDK.clearGlobalProperties();

4.5.在旧版安卓设备上收集安装推荐人

在安卓系统中，安装推荐人是 Singular 用于确定归因并帮助 Singular 检测和分析欺诈企图的最准确工具。它是 Google Play 商店提供的标识符，指向用户在安装应用程序之前点击的广告。

在使用最新 Google Play 商店版本的设备上，Singular SDK 会自动收集安装推荐人值（因为 Singular 已集成了最新的Google Play 推荐人 API）。

要在旧版本设备上收集安装推荐人，请按照Android SDK 指南中的说明进行操作。

5.遵守数据隐私法

5.1.限制数据共享

Singular提供隐私保护功能，帮助您与任何可能遵守消费者隐私法（如GDPR和CCPA（加州消费者隐私法））的合作伙伴合作。这些合作伙伴希望在最终用户同意共享其私人信息时得到通知。

限制数据共享

如果你已经实施了一种征求用户同意共享其信息的方法，请使用limitDataSharing方法通知 Singular 用户的选择：

• 使用limitDataSharing:NO表示用户同意（选择加入）共享其信息。
• 如果用户不同意，则使用limitDataSharing:YES。

Singular在"用户隐私回传"中使用限制数据分享，并将此信息传递给需要遵守相关规定的合作伙伴。更多信息请参阅"用户隐私和限制数据共享"。

// User has opted in to sharing data


SingularSDK.LimitDataSharing(false);

5.2.遵守 GDPR 的其他方法

Singular SDK 提供了几种方法来帮助你遵守 GDPR 政策，并让 Singular 了解用户是否同意追踪。

SingularSDK.TrackingOptIn();

SingularSDK.StopAllTracking();

SingularSDK.ResumeAllTracking();

SingularSDK.IsAllTrackingStopped();