获取 Singular SDK 密钥

在 Singular 账户中，进入 "开发工具 > SDK 集成 > SDK 密钥"，复制 SDK 密钥和秘钥。

将 Singular 添加为 mParticle 输出端

1. 在你的 mParticle 账户中，进入设置 > 输出，然后点击添加事件输出。
2. 从下拉列表中选择Singular。
3. 在 "事件配置"窗口中，输入配置名称，并输入在上一步中复制的 Singular 密钥和秘密。
4. 单击保存。

安装 Singular SDK

安装 Singular SDK：

1. 在应用程序中，在Link Binary With Libraries中添加 AdServices.framework，并将其标记为可选（仅适用于 iOS 14.3 及更高版本的设备）。

2. 在应用程序的 podfile 中添加 Singular MParticle pod：

   pod 'mParticle-Singular'

3. 在 podfile 目录中运行 "pod install"。

导入 Singular 库

要导入 Singular 库，请添加以下代码：

#import "MPKitSingular.h"

初始化 Singular SDK

每次打开应用程序时，都应调用 SDK 初始化代码。这是所有 Singular 归因功能的先决条件，它还会向 Singular 发送一个新的用户会话（会话用于计算用户保留率）。

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
      //initialize mParticle 
      MParticleOptions *options = [MParticleOptions optionsWithKey:@"<MPARTICLE_KEY>" secret:@"<MPARTICLE_SECRET>"];
      [[MParticle sharedInstance] startWithOptions:options]; 
      return YES; 
  }

[可选] 跟踪事件

Singular 可以收集应用程序内事件的相关数据，以帮助分析营销活动的效果并衡量关键绩效指标。

根据应用程序的不同，您可能需要跟踪用户登录、注册、教程完成或游戏等级提升等事件。

以下示例代码会向 Singular 报告一个名为 "event_name "的事件，并带有两个自定义属性。您将能在 Singular 报告中看到 "event_name "的发生次数。

MPEvent *event = [[MPEvent alloc] initWithName:@"event_name"
      type:MPEventTypeTransaction];
  event.customAttributes = @{@"category":@"Destination Intro",
      @"title":@"Paris"};
  [[MParticle sharedInstance] logEvent:event];

[可选] 跟踪收入

Singular 可以收集通过应用程序获得的收入数据，帮助分析营销活动的绩效和投资回报率。

Singular 会在报告、日志导出和回帖中为您提供这些数据。

要跟踪收入，请向 Singular 报告收入事件，如下例所示。该示例报告了应用内购买产品的情况，提供了产品名称、SKU、数量和价格。

// 1. Create the products
  MPProduct *product = [[MPProduct alloc] initWithName:@"product_name" sku:@"product_sku" quantity:@10     
                                                price:@100.00];
  // 2. Summarize the transaction
  MPTransactionAttributes *attributes = [[MPTransactionAttributes alloc] init];
  attributes.transactionId = @"ransaction_id";
  attributes.revenue = @400.00;
  attributes.tax = @10.00;
  
  // 3. Log the purchase event
  MPCommerceEventAction action = MPCommerceEventActionPurchase;
  MPCommerceEvent *revenueEvent = [[MPCommerceEvent alloc] initWithAction:action product:product];
  revenueEvent.transactionAttributes = attributes;
  [[MParticle sharedInstance] logEvent:revenueEvent];

[可选] 添加 SKAdNetwork 支持

SKAdNetwork 是 Apple 在不损害最终用户隐私的情况下确定移动安装归属的新框架。

SKAdNetwork 可让您在不共享用户个人身份信息的情况下衡量应用程序营销活动的绩效。

单一的 SKAdNetwork 解决方案 SKAN 可让您以最小的工程投入实施 SKAdNetwork。初始化 SKAN 后，您向 Singular 报告的每个事件都会在服务器端自动处理，根据您预定义的转换模型更新转换值。然后将新的转换值发回应用程序。此过程不断重复，直到测量期结束，应用程序将最新转换值发送到 SKAdNetwork。

欲了解更多信息，请参阅Singular 的 SKAdNetwork 解决方案简介和如何开始使用 SKAdNetwork。

以下示例代码在等待 ATT 同意 60 秒后启用 SKAN（请参阅 Singular iOS SDK：处理 AppTrackingTransparency 同意）。

[MPKitSingular setSKANOptions:YES isManualSkanConversionManagementMode:NO 
      withWaitForTrackingAuthorizationWithTimeoutInterval:@60.0 
      withConversionValueUpdatedHandler:^(NSInteger conversionValue) {
                    NSLog(@"conversion value %ld", conversionValue);
  }];

[可选] 处理深层链接

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

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

注意事项：

• Singular 使用iOS 通用链接进行深度链接。
• 要启用通用链接，请按照Singular Links Prerequisites 中的说明操作。
• 需要在 Singular 的 "应用程序 "页面设置应用程序 的深度链接目的地（请参阅 " 配置深度链接 URL"）。

使用 AppDelegate 处理深度链接：

添加对 SDK 初始化方法的调用，包括 onAttributionComplete：

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
      //initialize mParticle 
      MParticleOptions *options = [MParticleOptions optionsWithKey:@"<MPARTICLE_KEY>" secret:@"<MPARTICLE_SECRET>"];
      options.proxyAppDelegate = NO; 
      [[MParticle sharedInstance] startWithOptions:options]; 
      return YES; 
  }

还可在 AppDelegate 的 continueUserActivity 中调用 mParticle 的 continueUserActivity 方法：

- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity
restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler {
      [[MParticle sharedInstance] continueUserActivity:userActivity restorationHandler:restorationHandler];
      return YES;
  }

使用 SceneDelegate 处理深度链接：

在 SceneDelegate 的 continueUserActivity 和 willConnectToSession 中调用 mParticle 的 continueUserActivity 方法：

- (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session 
options:(UISceneConnectionOptions *)connectionOptions {
      NSUserActivity* userActivity =
      [[[connectionOptions userActivities] allObjects] firstObject];
      [[MParticle sharedInstance] continueUserActivity:userActivity restorationHandler:nil];
  }
  
  - (void)scene:(UIScene *)scene
      continueUserActivity:(NSUserActivity *)userActivity{
      [[MParticle sharedInstance] continueUserActivity:userActivity restorationHandler:nil];
  }

获取 Singular SDK 密钥

在 Singular 账户中，进入 "开发工具 > SDK 集成 > SDK 密钥"，复制 SDK 密钥和秘钥。

将 Singular 添加为 mParticle 输出

1. 在你的 mParticle 账户中，进入设置 > 输出，然后点击添加事件输出。
2. 从下拉列表中选择Singular。
3. 在 "事件配置"窗口中，输入配置名称，并输入在上一步中复制的 Singular 密钥和秘密。
4. 单击保存。

安装 SDK

1. 在构建脚本中添加 Singular 的 Maven 服务器，这是 Singular 工具包的要求。

   repositories {
         maven { url "http://maven.singular.net"}
         ...
     }

2. 将套件依赖关系添加到应用程序的 build.gradle：

   dependencies {
         compile 'com.mparticle:android-singular-kit:5+'
     }

初始化 SDK

每次打开应用程序时，都应调用 SDK 初始化代码。它是所有 Singular 归因功能的先决条件，同时也会向 Singular 发送一个新的用户会话（会话用于计算用户留存）。你可以在 mParticle 面板和 Singular 报告中跟踪会话。

//import mParticle
  import com.mparticle.MParticle;
  import com.mparticle.MParticleOptions;
  
  public class ExampleActivity extends Activity {
      @Override
      public void onCreate() {
          super.onCreate();
          MParticleOptions options = MParticleOptions.builder(this)
                  .credentials("REPLACE ME WITH KEY", "REPLACE ME WITH SECRET")
                  .build();
          MParticle.start(options);
      }
  }

[可选] 设置用户 ID

Singular SDK 可以将用户 ID 从你的应用程序发送到 Singular。 用户 ID 可以是用户名、电子邮件地址、随机生成的字符串，或者你用作用户 ID 的任何标识符。

Singular 会在用户级数据导出和内部 BI 回传（如果配置了此类回传）中使用用户 ID。

一旦设置了用户 ID，它就会与任何会话和事件一起发送。用户 ID 会一直存在，直到取消设置或卸载应用程序为止。关闭/重启应用程序不会取消设置用户 ID。

IdentityApiRequest identityRequest = IdentityApiRequest.withEmptyUser()
          .email("foo@example.com")
          .customerId("123456")
          .build();
  MParticle.getInstance().Identity().login(identityRequest);

[可选] 跟踪事件

Singular 可以收集应用程序内事件的相关数据，以帮助分析营销活动的效果并衡量关键绩效指标。

根据应用程序的不同，您可能需要跟踪用户登录、注册、教程完成或游戏等级提升等事件。

以下示例代码以 JSONObject 格式向 Singular 报告名为 "test_event "的事件，并附带附加信息（customAttributes）。

Map<String, String> customAttributes = new HashMap<String, String>();
            customAttributes.put("category", "event_category");
            MPEvent event = new MPEvent.Builder("test_event", MParticle.EventType.Navigation)
                   .customAttributes(customAttributes)
                   .build();
            MParticle.getInstance().logEvent(event);
          

[可选] 跟踪收入

Singular 可以通过接收来自 mParticle 的 Product.PURCHASE 事件来收集应用程序的收入数据。

事件收入的计算公式为数量 * 产品成本。

Product product = new Product.Builder("extra life", "extra-life", 100.00)
          .quantity(4.0)
          .build();
  TransactionAttributes attributes = new TransactionAttributes("123123")
          .setRevenue(430.00)
          .setTax(30.00);
  
  CommerceEvent event = new CommerceEvent.Builder(Product.PURCHASE, product)
          .transactionAttributes(attributes)
          .currency("USD")
          .build();
  
  MParticle.getInstance().logEvent(event);

[可选] 处理深层链接

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

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

注意：

• 要为您的应用程序启用深度链接，请参阅奇异链接先决条件。
• 需要在 Singular 的 "应用程序 "页面设置应用程序 的深度链接目的地（请参阅 " 配置深度链接 URL"）。

要处理深度链接，请按以下示例实现 AttributionListener。请注意，您需要在每个主入口活动中实现 AttributionListener。

public class ActivityDeeplink extends AppCompatActivity implements AttributionListener {
  
      @Override
      protected void onCreate(Bundle savedInstanceState) {
          super.onCreate(savedInstanceState);
          MParticleOptions options = MParticleOptions.builder(this)
                  .credentials("REPLACE ME WITH KEY", "REPLACE ME WITH SECRET")
                  .attributionListener(this)
                  .logLevel(MParticle.LogLevel.VERBOSE)
                  .build();
          MParticle.start(options);
      }
  
      @Override
      public void onResult(@NonNull @NotNull AttributionResult attributionResult) {
          if (attributionResult.getServiceProviderId() == MParticle.ServiceProviders.SINGULAR) {
              String deeplink = attributionResult.getLink();
              JSONObject data = attributionResult.getParameters();
              String passthrough = data.optString("passthrough", null);
              // Deal with deep link
          }
      }
  
      @Override
      public void onError(@NonNull @NotNull AttributionError attributionError) {
          // Deal with error
      }
  }