Rakam-iOS 4.0.4

Rakam-iOS 4.0.4

×

测试已测试✓
语言语言 Obj-CObjective C
许可证 未知
发布最新发布2018年6月

由Burak Emre Kabakci维护。

Rakam-iOS 4.0.4

  • 作者：
  • Rakam

Rakam iOS SDK

用于跟踪事件到 Rakam 的 iOS SDK。

CocoaPods

一个 演示应用程序 可以展示简单的集成。

查看我们的 SDK 文档，了解所有可用的 SDK 方法和类。

我们的 iOS SDK 还支持 tvOS。有关更多信息，请参阅 以下内容。

设置

  1. 如果您尚未注册，请访问 https://rakam.com 并注册一个账号。您将收到一个 API 密钥。

  2. 下载源代码并解压。

    或者，您可以直接从 GitHub 拉取。如果您使用 CocoaPods，请将以下行添加到您的 Podfile 中：pod 'Rakam-iOS', '~> 4.0.4'。如果您使用 CocoaPods，您可能可以跳过步骤 3 和 4。

  3. 将“Rakam”子文件夹复制到 Xcode 中您项目的源代码中。检查“将项目复制到目标组的文件夹中（如果需要）”。

  4. Rakam 的 iOS SDK 需要SQLite库，该库包含在iOS中，但需要额外的构建标志来启用。在您的项目“链接”部分的“构建设置”和您的目标“构建设置”中，在“链接” -> “其他链接器标志”下，添加标志 -lsqlite3.0。

  5. 在每个使用分析的部分，顶部导入 Rakam.h

    #import "Rakam.h"

  6. 在您的 YourAppNameAppDelegate.m 文件的 application:didFinishLaunchingWithOptions: 方法中初始化 SDK

    [[Rakam instance] initializeApiKey:[NSURL URLWithString:@"YOUR_RAKAM_API"] : @"YOUR_API_KEY_HERE"];

  7. 要在应用中的任何位置跟踪事件，请调用

    [[Rakam instance] logEvent:@"EVENT_IDENTIFIER_HERE"];

  8. 事件将本地保存。上传以批处理形式，每 30 个事件和每 30 秒以及应用关闭时发生。在您的应用中调用 logEvent 后，您将立即在 Rakam 网站上看到数据。

追踪事件

作为开发者，思考你所关注的事件的类型非常重要。你应该目标是在网站上追踪20到200种类型的事件。常见的类型包括用户发起的操作（例如按下按钮）和希望用户完成的事件（例如填写表单、完成关卡或进行支付）。

单个调用logEvent不应包含超过1000个事件属性。同样，单个调用setUserProperties也不应包含超过1000个用户属性。如果超过1000项的限制，则属性将被删除并记录警告。我们对事件和属性上限做了非常保守的估计，我们预计在实际应用场景中不会被超过。如果你觉得你的用例将超过这些限制，请联系[email protected]。

追踪会话

会话是用户在应用前景中的时间段。彼此之间间隔5分钟内的会话会合并为单个会话。在iOS SDK中，会话自动追踪。当SDK初始化时，它会确定应用是在前台还是后台启动，并在前台启动时开始新的会话。当应用在离线状态下5分钟或更长时间后再次进入前台时，将创建新的会话。如果应用在后台且记录了事件，则在应用进入后台或上次记录事件超过5分钟的情况下会创建新的会话。否则，记录的后台事件将作为当前会话的一部分。

你可以通过更改变量minTimeBetweenSessionsMillis来调整会话扩展的时间窗口。

[Rakam instance].minTimeBetweenSessionsMillis = 30 * 60 * 1000; // 30 minutes
[[Rakam instance] initializeApiKey:[NSURL URLWithString:@"YOUR_RAKAM_API_URL"] : @"YOUR_API_KEY_HERE"];

默认情况下，不再发送开始和结束会话事件。要重新启用，请在初始化SDK之前添加此行。

[[Rakam instance] setTrackingSessionEvents:YES];
[[Rakam instance] initializeApiKey:[NSURL URLWithString:@"YOUR_RAKAM_API_URL"] : @"YOUR_API_KEY_HERE"];

你还可以记录跨会话的事件。跨会话事件具有会话_id为-1，并且不被视为当前会话的一部分，这意味着它们不会扩展当前会话。例如，如果你正在记录由推送通知触发的事件，这可能会很有用。你可以通过在调用logEvent时将输入参数outOfSession设置为true来记录跨会话事件。

[[Rakam instance] logEvent:@"EVENT_IDENTIFIER_HERE" withEventProperties:nil outOfSession:true];

你还可以通过在调用identify时将输入参数outOfSession设置为YES来记录为跨会话的标识事件。

RakamIdentify *identify = [[RakamIdentify identify] set:@"key" value:@"value"];
[[Rakam instance] identify:identify outOfSession:YES];

获取会话ID

可以使用辅助方法getSessionId来获取当前会话ID的值。

long long sessionId = [[Rakam instance] getSessionId];

设置自定义用户ID

如果你的应用有自己的登录系统，并且你想跟踪用户，可以在任何时候调用setUserId:。

[[Rakam instance] setUserId:@"USER_ID_HERE"];

你还可以将用户ID作为参数添加到initializeApiKey:调用中。

[[Rakam instance] initializeApiKey:[NSURL URLWithString:@"YOUR_RAKAM_API_URL"] : @"YOUR_API_KEY_HERE" userId:@"USER_ID_HERE"];

注销和匿名用户

如果用户注销，或者你想以匿名用户的形式记录事件，你需要做两件事：1) 将userId设置为nil 2) 重新生成一个新的deviceId。这样做后，来自当前用户/设备的所有事件将出现在Rakam仪表板中的全新用户下。注意：如果你选择这样做，将无法看到两个用户是否使用了同一设备。

[[Rakam instance] setUserId:nil];  // not string nil
[[Rakam instance] regenerateDeviceId];

设置事件属性

通过将NSDictionary对象作为logEvent:withEventProperties的第二个参数传递，可以为任何事件附加额外的数据。

NSMutableDictionary *eventProperties = [NSMutableDictionary dictionary];
[eventProperties setValue:@"VALUE_GOES_HERE" forKey:@"KEY_GOES_HERE"];
[[Rakam instance] logEvent:@"Compute Hash" withEventProperties:eventProperties];

注意：键的类型应该是NSString，值应该是NSString、NSNumber、NSArray、NSDictionary或NSNull。如果你尝试使用不支持的数据类型，则会看到警告。

用户属性和用户属性操作

SDK支持对单个用户属性的set、setOnce、unset以及add操作。这些操作通过提供的RakamIdentify接口进行声明。可以在一个单独的RakamIdentify对象中链式调用多个操作。然后，将RakamIdentify对象传递给Rakam客户端以发送到服务器。操作的结果将立即在仪表板上可见，并应用于后续记录的事件。注意，在RakamIdentify对象上每个操作都返回相同的实例，允许您链式调用多个操作。

要使用RakamIdentify接口，您首先需要包含以下头文件：

#import "RakamIdentify.h"

  1. set：此操作设置用户属性的值。

    RakamIdentify *identify = [[[RakamIdentify identify] set:@"gender" value:@"female"] set:@"age" value:[NSNumber numberForInt:20]];
[[Rakam instance] identify:identify];

  2. setOnce：此操作只设置用户属性的值一次。后续对该用户属性的setOnce操作将被忽略。以下示例中，sign_up_date将被设置为
    2015年8月24日一次，接下来到2015年9月14日的设置将被忽略。

    RakamIdentify *identify1 = [[RakamIdentify identify] setOnce:@"sign_up_date" value:@"09/06/2015"];
[[Rakam instance] identify:identify1];

RakamIdentify *identify2 = [[RakamIdentify identify] setOnce:@"sign_up_date" value:@"10/06/2015"];
[[Rakam instance] identify:identify2];

  3. unset：这将取消设置并删除用户属性。

    RakamIdentify *identify = [[[RakamIdentify identify] unset:@"gender"] unset:@"age"];
[[Rakam instance] identify:identify];

  4. add：这将通过某个数值递增用户属性。如果用户属性尚未设置值，则在递增之前将其初始化为0。

    RakamIdentify *identify = [[[RakamIdentify identify] add:@"karma" value:[NSNumber numberWithFloat:0.123]] add:@"friends" value:[NSNumber numberWithInt:1]];
[[Rakam instance] identify:identify];

  5. append：这将将值追加到用户属性中。如果用户属性尚未设置值，则在追加新值之前将将其初始化为空列表。如果用户属性已有值且不是列表，则将其转换为列表，并追加新的值。

    NSMutableArray *array = [NSMutableArray array];
[array addObject:@"some_string"];
[array addObject:[NSNumber numberWithInt:56]];
RakamIdentify *identify = [[[RakamIdentify identify] append:@"ab-tests" value:@"new-user-test"] append:@"some_list" value:array];
[[Rakam instance] identify:identify];

  6. prepend：这将将在用户属性的值开头添加值。 prepend意味着在给定列表的开头插入值。如果用户属性尚未设置值，则在添加新值之前将将其初始化为空列表。如果用户属性已存在值且不是列表，则将其转换为列表，并添加新的值。

    NSMutableArray *array = [NSMutableArray array];
[array addObject:@"some_string"];
[array addObject:[NSNumber numberWithInt:56]];
RakamIdentify *identify = [[[RakamIdentify identify] append:@"ab-tests" value:@"new-user-test"] prepend:@"some_list" value:array];
[[Rakam instance] identify:identify];

注意：如果用户属性在同一个Identify对象上的多个操作中使用，则只有第一个操作将被保存，其余将被忽略。在以下示例中，只有设置操作将被保存，而添加和取消设置将被忽略。

RakamIdentify *identify = [[[[RakamIdentify identify] set:@"karma" value:[NSNumber numberWithInt:10]] add:@"friends" value:[NSNumber numberWithInt:1]] unset:@"karma"];
    [[Rakam instance] identify:identify];

用户属性中的数组

SDK支持用户属性中的数组。上述用户属性操作中（除了add），都可以接受NSArray或NSMutableArray。您可以直接使用set设置数组，或使用append生成数组。

NSMutableArray *colors = [NSMutableArray array];
[colors addObject:@"rose"];
[colors addObject:@"gold"];
NSMutableArray *numbers = [NSMutableArray array];
[numbers addObject:[NSNumber numberWithInt:4]];
[numbers addObject:[NSNumber numberWithInt:5]];
RakamIdentify *identify = [[[[RakamIdentify identify] set:@"colors" value:colors] append:@"ab-tests" value:@"campaign_a"] append:@"existing_list" value:numbers];
[[Rakam instance] identify:identify];

使用setUserProperties设置多个属性

您可以使用setUserProperties简写方法同时设置多个用户属性。此方法简单地将RakamIdentify set和identify包装起来。

NSMutableDictionary *userProperties = [NSMutableDictionary dictionary];
[userProperties setValue:@"VALUE_GOES_HERE" forKey:@"KEY_GOES_HERE"];
[userProperties setValue:@"OTHER_VALUE_GOES_HERE" forKey:@"OTHER_KEY_GOES_HERE"];
[[Rakam instance] setUserProperties:userProperties];

使用 clearUserProperties 清除用户属性

您可以使用 clearUserProperties 一次性清除所有用户属性。注意：此结果将不可逆！

[[Rakam instance] clearUserProperties];

允许用户退订

要停止用户的全部事件和会话记录，请调用 setOptOut

[[Rakam instance] setOptOut:YES];

可以通过再次调用 setOptOut 并将 enabled 设置为 NO 来重启日志记录。在外部可退订期间，甚至在外部可退订禁用后，都不会记录任何事件。

跟踪收入

如今，为用户跟踪收入的首选方法是使用提供的 RakamRevenue 接口与 logRevenue 结合。将存储每个收入交易并允许您定义多个特殊的收入属性（如 revenueType, productIdentifier 等），这些属性用于 Rakam 控制面板的收入选项卡。您现在也可以通过 eventProperties 字段将事件属性添加到收入事件中。然后，将这些 RakamRevenue 实例对象传递给 logRevenue，以将作为收入事件发送到 Rakam 服务器。这使得我们可以在 Rakam 网站上自动显示与收入相关的数据，包括每日活跃用户平均收入 (ARPDAU)、1、7、14、30、60 和 90 天收入、终身价值 (LTV) 估计，以及按广告活动细分组和每日/每周/每月细分组的收入。

重要提示：Rakam 目前不支持货币转换。在发送到 Rakam 之前，应将所有收入数据标准化为您的选择货币。

要使用 Revenue 接口，你首先需要导入类

#import "RakamRevenue.h"

每次用户生成收入时，你都会创建一个 RakamRevenue 对象并填写收入属性

RakamRevenue *revenue = [[[RakamRevenue revenue] setProductIdentifier:@"productIdentifier"] setQuantity:3];
[revenue setPrice:[NSNumber numberWithDouble:3.99]];
[[Rakam instance] logRevenue:revenue];

price 是一个必填字段。如果没有指定，quantity 默认为 1。《code>quantity 默认为 1。reicept 是一个必填字段，如果你想验证收入事件。每个字段都有一个相应的 set 方法（例如 setProductId、setQuantity 等）。下表描述了可用的不同字段

名称 类型 描述 默认
productId NSString 可选：产品的标识符（可以来自 SKPaymentTransaction.payment.productIdentifier） nil
quantity NSInteger 必需：购买产品的数量。如果没有指定，则默认为 1。收入 = 数量 * 价格 1
price NSNumber 必需：购买产品的价格（可以是负数）。收入 = 数量 * 价格 nil
收入类型 NSString 可选：收入的类型（例如：税收、退款、收入） nil
收据 NSData 可选：如果您想验证收入事件，则需要提供 nil
事件属性 NSDictionary 可选：将包含在收入事件中的事件属性的NSDictionary nil

注意：价格可以是负数，这可能有助于追踪收入损失，例如退款或成本。此外，您可以通过传递字符串键值对的NSDictionary来在收入事件上设置事件属性，就像在调用logEvent时一样。然而，这些事件属性仅在“事件细分”标签中可见，而不是在“收入”标签中。

收入验证

默认情况下，在iOS SDK上记录的收入事件在Rakam仪表板上显示为未经验证的收入事件。 要启用收入验证，请将您的iTunes Connect In App Purchase Shared Secret复制到Rakam上您的应用程序的管理部分。您必须在Rakam中为每个想要启用收入验证的应用程序设置一个密钥。

然后在购买交易成功后，将收据数据添加到Revenue对象中

RakamRevenue *revenue = [[[RakamRevenue revenue] setProductIdentifier:@"productIdentifier"] setQuantity:1];
[[revenue setPrice:[NSNumber numberWithDouble:3.99]] setReceipt:receiptData];
[[Rakam instance] logRevenue:revenue];

receipt:从应用商店获取的收据NSData。有关获取收据数据的详细信息，请参阅Apple关于收据验证的指南。

向后兼容性

现有的logRevenue方法仍然有效，但已弃用。例如，revenueType字段将不会在旧方法记录的事件中出现，因此这些事件的收入细分在Rakam仪表板中会受到限制。

跟踪多个Rakam应用程序的事件

Rakam iOS SDK支持将事件记录到多个Rakam应用程序（多个API密钥）。如果您想将事件记录到多个Rakam应用程序，您需要为每个Rakam应用程序使用不同的实例。新创建的每个实例都将有其自己的apiKey、userId、deviceId和设置。

您需要为每个Rakam应用程序/实例指定一个名称，并且在调用函数时始终一致地使用该名称。 重要：一旦为该实例选择了名称，就不能更改它。 每个实例的数据和设置都与其名称相关联，并且您需要继续使用该实例名称的所有未来版本的应用程序以保持数据连续性，因此请谨慎选择实例名称。注意，这些名称不需要与Rakam仪表板中您的应用程序的名称相匹配，但它们需要在整个代码中保持一致。您还需要确保每个实例用正确的apiKey初始化。

实例名称必须是非空且非空的字符串。名称不区分大小写。您可以通过调用 [Rakam instanceWithName:@"INSTANCE_NAME"] 来按名称获取每个实例。

如前所述，每个新创建的实例都将有自己的 apiKey、userId、deviceId 和设置。 您需要重新配置每个实例的所有设置。 例如，如果您想跟踪会话事件，则必须在每个实例上调用 setTrackingSessionEvents:YES。这确实赋予您为每个实例拥有不同设置的自由。

向后兼容性 - 从单个 Rakam 应用升级到多个应用

如果您在 v3.6.0 之前使用单个应用跟踪用户，可能会想知道现有数据、现有设置以及返回用户（已拥有 deviceId 和/或 userId 的用户）将发生什么。所有历史数据和设置都维护在 default 实例上，可以通过不带实例名称调用获取：[Rakam instance]。这是您习惯与 Rakam SDK 交互的方式，这意味着您的所有现有跟踪代码应该像之前一样正常工作。

如何设置和记录两个独立应用的示例

[[Rakam instance] initializeApiKey:[NSURL URLWithString:@"YOUR_RAKAM_API_URL"] : @"12345"]; // existing app, existing settings, and existing API key
[[Rakam instanceWithName:@"new_app"] initializeApiKey:[NSURL URLWithString:@"YOUR_RAKAM_API_URL"] : @"67890"]; // new app, new API key

[[Rakam instanceWithName:@"new_app"] setUserId:@"[email protected]"]; // need to reconfigure new app
[[Rakam instanceWithName:@"new_app"] logEvent:@"Clicked"];

RakamIdentify *identify = [[RakamIdentify identify] add:@"karma" value:[NSNumber numberWithInt:1]];
[[Rakam instance] identify:identify];
[[Rakam instance] logEvent:@"Viewed Home Page"];

在应用间同步设备 Id

如前所述，每个新实例将有自己的 deviceId。如果您想您的应用程序共享相同的 deviceId，可以通过 getDeviceId 和 setDeviceId 方法在初始化后这样做。以下是将现有 deviceId 复制到 new_app 实例的示例

NSString *deviceId = [[Rakam instance] getDeviceId]; // existing deviceId
[[Rakam instanceWithName:@"new_app"] setDeviceId:deviceId]; // transferring existing deviceId to new app

tvOS

此 SDK 将与 tvOS 应用一起工作。遵循与 iOS 应用相同的 设置说明。

请注意一点： tvOS 应用没有持久存储（只有临时存储），因此对于 tvOS，SDK 默认配置为即时上传事件（将 eventUploadThreshold 设置为 1）。假设 Apple TV 设备拥有稳定的互联网连接，所以立即上传事件是合理的。如果您希望恢复到 iOS 批处理行为，可以通过更改 eventUploadThreshold 来实现（对于 iOS 默认设置为 30）。

[[Rakam instance] setEventUploadThreshold:30];

Swift

此 SDK可与 Swift 一起使用。如果您正在复制源文件或使用 CocoaPods 而没有设置use_frameworks!指令，应按照文档创建一个桥接头，并在桥接头中添加以下行。

#import "Rakam.h"

如果您已设置 use_frameworks!，则不应使用桥接头，而是应在 swift 文件中使用以下行。

import Rakam_iOS

无论哪种情况，都可以使用 Rakam.instance().method(...) 调用 Rakam 方法。

高级

此 SDK 会自动从手机中抓取有用的数据，包括应用版本、手机型号、操作系统版本和运营商信息。

位置跟踪

如果用户已授权您的应用位置权限，则 SDK 还会获取用户的位置。Rakam 从不会提示用户自己请求位置权限，这必须由您的应用来完成。

Rakam只会启动应用时查询一次位置，每次打开应用程序时查询一次，以及每次第一次授权时查询一次。没有连续跟踪位置，尽管您可以调用[[Rakam instance] updateLocation] 强制 Rakam 获取最新位置。请注意，此操作会消耗更多用户设备上的资源，因此请明智使用。

如果您希望禁用应用执行的位置跟踪，可以在任何时间调用[[Rakam instance] disableLocationListening]。如果您想要在应用启动时禁用位置跟踪，请在调用initializeApiKey:之前调用disableLocationListening。您可以通过调用 [[Rakam instance] enableLocationListening] 在 Rakam 中重新启用位置跟踪。

自定义设备ID

如果可用，设备ID设置为供应商标识符（IDFV），否则将随机生成。然而，您可以通过在初始化API密钥之前调用[[Rakam实例] 使用广告ID作为设备ID]，选择在可用的情况下使用广告标识符（IDFA）。您还可以使用[[Rakam实例] 获取设备ID]检索Rakam使用的设备ID。

如果您有自己的设备ID跟踪系统并希望设置自定义设备ID，可以使用[[Rakam实例] 设置设备ID:@"CUSTOM_DEVICE_ID"]; 注意：除非您确实知道自己在做什么，否则不建议这样做。 确保您设置的设备ID足够唯一（我们建议使用类似于UUID的东西 - 看看[RKMUtils 生成UUID]中如何生成的示例）以防止与我们系统中其他设备的冲突。

ARC

此代码将与ARC和非ARC项目一起工作。使用预处理器宏确定正在使用哪个编译器版本。

iOS扩展

SDK允许在iOS扩展中进行跟踪。按照设置说明操作。在第6步中，不是在application:didFinishLaunchingWithOptions:中初始化SDK，而是在您的扩展的viewDidLoad方法中初始化SDK。

注意事项

  1. viewDidLoad方法将在您的扩展每次打开时都会被调用。这意味着我们的SDK的initializeApiKey方法将每次都被调用；然而，这是可以接受的，因为一旦执行过第一次调用，它将安全地忽略后续的调用。如果您愿意，可以用类似dispatch_once块的东西来保护初始化。

  2. 我们对会话的定义是针对应用使用的。根据您期望的扩展使用情况，您可能希望禁用trackingSessionEvents，或将minTimeBetweenSessionsMillis扩展得更长于5分钟。您应该对这些设置进行实验，以获取所需的会话定义。

  3. 另外，您可能想要将eventUploadPeriodSeconds减少到小于30秒，以便在用户不会长时间保留您的扩展时以更短的间隔上传事件。您还可以手动调用[[Rakam实例] 上传事件];来手动强制上传。

这是一个简单的示例应用程序，展示了如何在扩展中安装iOS SDK。

调试日志

默认情况下，只有关键错误会被记录到控制台。要启用调试日志，将Objective-C文件顶部的RAKAM_DEBUG从0修改为1。

默认情况下会打印错误信息。要禁用错误日志，请在Rakam.m中将RAKAM_LOG_ERRORS从1修改为0。