RakutenAnalytics SDK

分析 模块提供跟踪事件的 API，并自动将生命周期事件的子集发送到 Rakuten Analytics Tracker (RAT) 服务。

1. RAnalytics SDK
2. 需求
3. 如何安装
4. 配置
5. 使用 SDK
6. 示例应用
7. 应用商店提交流程
8. 故障排除
9. 常见问题解答

需求

此模块支持 iOS 12.0 及以上版本。已与 iOS 12.5 及以上版本进行过测试。我们的最低支持版本将根据 OS 版本的使用情况每年更新。

支持 Xcode >= 14.1。Swift >= 5.7.1 支持。

注意：SDK 可能可以在较旧版本的 Xcode 上构建，但并未正式支持或测试。

如何安装

CocoaPods

要使用模块的默认配置，您的 Podfile 应该包含

pod 'RakutenAnalytics'

运行 pod install 安装模块及其依赖项。

Swift Package Manager

在 Xcode 中打开您的项目设置，并在 'Swift Packages' 选项卡中添加一个新的包

• 仓库 URL: [email protected]:rakutenanalytics/ios-rakutenanalytics.git
• 版本设置：10.0.1 "Up to Next Major"

为您的目标选择 RAnalytics 产品。如果您想链接其他目标（通知服务扩展、通知内容扩展等），请转到该目标的 'Build Phases'，然后在 'Link Binary With Libraries' 中点击 + 按钮并添加 RAnalytics。

将模块导入到您的应用中使用

Swift

import RakutenAnalytics

Objective-C

@import RakutenAnalytics;

配置

证书

您必须有一个RAT账户ID和应用ID，才能使用Rakuten Analytics Tracker跟踪事件。

构建时配置

应用程序必须在它们的Info.plist中配置它们的RAT标识符（RATAccountIdentifier和RATAppIdentifier），如下所示

否则

• RAnalytics SDK 在 调试模式 下，当应用程序的 Info.plist 中缺少 RATAccountIdentifier 和 RATAppIdentifier 键时，会抛出异常。
• 在 发布模式 下，当应用程序的 Info.plist 中缺少 RATAccountIdentifier 和 RATAppIdentifier 键时，RAnalytics SDK 跟踪将 禁用。

使用 Kibana 验证集成成功

Kibana 的 STG 和 PROD 站点可用于检查应用程序发送的事件。

要查找应用程序的所有分析数据，您可以搜索应用程序标识符 aid:<your app id> 或 app_name:<your bundle id>。

要查找某种事件类型的数据，例如 标准事件 之一，您可以在搜索查询中添加 etype，例如 aid:999 AND etype:_rem_launch。

使用 SDK

处理登录

需要手动设置和取消设置成员标识符以跟踪具有正确成员标识符的登录和注销事件。在大多数情况下，您设置的成员标识符应是成员的标识符。成员标识符可以从 IDSDK ID 令牌中提取或作为 String 值传递。

应使用 setMemberIdentifier 通知 RAnalytics SDK 用户的成员标识符。

    AnalyticsManager.shared().setMemberIdentifier(%member_identifier%)

注意：设置成员标识符后，将自动跟踪 _rem_login。

处理登录失败

如果用户登录失败，请使用 setMemberError 通知 RAnalytics SDK，如下所示

    AnalyticsManager.shared().setMemberError(error)

注意：设置成员错误后，会自动跟踪 _rem_login_failure。

处理登出

当用户登出时，请使用 removeMemberIdentifier 通知 RAnalytics SDK，如下所示

    AnalyticsManager.shared().removeMemberIdentifier()

注意：删除成员标识后，会自动跟踪 _rem_logout。

跟踪标准事件

使用 RAnalyticsEvent#initWithName:parameters: 创建事件，并通过调用它们的 track 方法进行缓冲。

跟踪通用事件

跟踪通用事件需要依赖于能够处理当前注册事件的跟踪器。

AnalyticsManager.Event(name: "my.event", parameters: ["foo": "bar"]).track()

跟踪 RAT 特定事件

具体的跟踪器 RAnalyticsRATTracker 会自动注册并交互于 Rakuten Analytics Tracker (RAT)。您也可以使用 RAnalyticsRATTracker#eventWithEventType:parameters: 创建仅由 RAT 处理的事件。

注意： 我们SDK会自动为您追踪多个RAT参数，因此在创建事件时无需包含那些参数： acc、aid、etype、powerstatus、mbat、dln、loc、mcn、model、mnetw、mori、mos、online、cka、ckp、cks、ua、app_name、app_ver、res、ltm、ts1、tzo、userid和ver。

RAnalyticsRATTracker.shared().event(eventType: "click", parameters:["pgn": "coupon page"]).track()

您可以在创建事件时，通过在parameters字典中包含相应键来覆盖acc和aid的默认值。注意： acc和aid必须是整数。

RAnalyticsRATTracker.shared().event(eventType: "click", parameters:["acc": 123, "aid": 456]).track()

标准事件

SDK将自动将某些操作的事件发送到乐天分析追踪器。所有这些事件的类型参数都以_rem_为前缀。我们还为这些提供了命名常量。

需求条件

以下表格显示了由分析模块自动跟踪的每个标准事件所需的组件。

自动生成的状态属性

SDK 将自动生成有关设备状态的某些属性，并将它们传递给每个已注册的跟踪器，以处理事件。

在 iOS 扩展中跟踪事件

警告

不要直接调用 AnalyticsManager 单例来在您的 iOS 扩展中跟踪事件，否则您将收到

• 缺失参数，例如成员标识符
• 不正确的端点 URL

请改用 iOS 扩展事件跟踪功能。

如何使用 iOS 扩展事件跟踪功能

要启用 iOS 扩展事件跟踪，请在您的 主应用程序 中设置以下属性

AnalyticsManager.shared().enableExtensionEventTracking = true

然后您可以使用以下函数在您的 iOS 扩展中跟踪事件

AnalyticsEventPoster.post(name: "myEventName", parameters: ["key1": "value1"])

在UIKit的UIViewController中跟踪事件

页面访问事件（etype = pv）会自动跟踪UIViewController实例。

UIViewController限制

以下UIViewController子类不跟踪页面访问事件

• UINavigationController
• UISplitViewController
• UIPageViewController
• UITabBarController

UIView限制

当UIViewController的视图类型为以下内容时不跟踪页面访问事件

• UIAlertView
• UIActionSheet
• UIAlertController

其他限制

• 私有的Apple类不会作为页面访问事件跟踪。
• UIView的window属性类型必须是UIWindow类的类型。

在 SwiftUI 视图中跟踪事件

要在您的 SwiftUI 应用中跟踪页面访问事件（etype = pv），请在 SwiftUI 视图主体中调用此函数

public func rviewOnAppear(pageName: String, perform action: (() -> Void)? = nil) -> some View

上述函数内部调用 SwiftUI 的 onAppear。请参阅 https://developer.apple.com/documentation/SwiftUI/AnyView/onAppear%28perform:%29

示例

struct ContentView: View {
    var body: some View {
        NavigationView {
            VStack {
                NavigationLink(destination: PageView()) {
                    Text("Page 1")
                }
                NavigationLink(destination: PageView()) {
                    Text("Page 2")
                }
            }.rviewOnAppear(pageName: "contentView") {
            }
        }
    }
}

UI交互

以下代码示例可用于跟踪按钮点击。它使用 RAT 的标准 click 事件，并在 pgn、target 和 gol 参数中分别传递页面名称、被点击元素的 id 和目标 id。

@IBAction func buttonTapped(sender: UIButton) {
    RAnalyticsRATTracker.shared().event(eventType: "click",
                             parameters:["pgn": "Main",
                                         "target": "search_btn",
                                         "gol": "goal123456"]).track()
}

跟踪自定义事件

注意： 此示例使用 RAnalyticsRATTracker 发送 RAT 特定的参数。如果您使用的是自定义跟踪器，则应使用 RAnalyticsEvent。

以下是一个使用自定义参数跟踪事件的示例。它使用前面示例中使用的标准 pv RAT 事件，并在接受此目的的 cp 字典中传递一些自定义 custom_param_## 参数。

RAnalyticsRATTracker.shared().event(eventType: "pv",
                         parameters:["pgn": "Main",
                                     "cp": ["custom_param_1": "value",
                                            "custom_param_2": 10,
                                            "custom_param_3": true]]).track()

示例应用

• 运行 bundle exec fastlane ios build_sample
  • 默认情况下，RAnalyticsSample 应用依赖于编译后的 RAnalytics 框架，该框架通过此命令调用构建。它还将安装依赖项。
• 在 Xcode 中打开 Samples/RAnalyticsSample.xcworkspace，然后运行

App Store 提交流程

苹果要求您在将您的应用发布到 App Store 时公开您的广告标识符（IDFA）的使用情况。

IDFA 使用披露

1. 在应用中提供服务广告。

如果您应用包含广告，请勾选此框。

2. 将此应用的安装与之前提供的广告关联

勾选此复选框。Rakuten SDK 使用 IDFA 进行安装归因。

3. 将在此应用内进行的操作归因于之前投放的广告

勾选此复选框。Rakuten SDK 使用 IDFA 进行再定向广告归因。

5. iOS 限制广告跟踪

Rakuten SDK 完全符合以下苹果的要求

在进行任何广告跟踪之前，检查此属性的值。如果值为“NO”，则仅使用广告标识符进行以下目的：频率限制、转换事件、估计唯一用户数量、安全与欺诈检测和调试。

Rakuten SDK 仅使用 IDFA 进行转换事件、估计唯一用户数量、安全与欺诈检测。

故障排除

如何在不使用use_frameworks!的情况下构建项目！

RAnalytics 是一个 Swift 框架，包含自定义模块映射。

如果您的应用程序 Podfile 中未定义use_frameworks!，则会出现以下 Cocoapods 错误

目前不支持使用自定义模块映射的 Swift 静态库。

为了解决这个问题

1. 将 cocoapods-user-defined-build-types 插件添加到您的 Podfile 中
2. 如下声明 RAnalytics 以及其依赖项为 static_framework

plugin 'cocoapods-user-defined-build-types'
enable_user_defined_build_types!

target 'MyApp' do
  pod 'RAnalytics', :build_type => :static_framework
end

注意： cocoapods-user-defined-build-types 插件由第三方开发，我们无法保证其支持的持续性。

RAnalytics Swift Package checkout 提示

如果您无法在 Xcode 中检出 RAnalytics Swift Package，请执行以下两条命令

/usr/libexec/Plistbuddy -c "Add :IDEPackageSupportUseBuiltinSCM bool 1" ~/Library/Preferences/com.apple.dt.Xcode.plist
xcodebuild -scheme MyScheme -resolvePackageDependencies -usePackageSupportBuiltinSCM

常见问题解答

构建和运行模块

• 克隆或分叉 iOS 分析仓库
• 使用 cd 命令切换到仓库文件夹
• 运行 bundle install --path vendor/bundle

单元测试

• 运行 bundle exec pod install 以安装依赖
• 在 Xcode 中打开 CI.xcworkspace 文件，然后构建/运行

为App Store构建应用

Xcode 13引入了一个选项（默认启用）以自动管理应用版本编号。启用此选项后导出您的应用将破坏Analytics SDK的框架版本跟踪功能。

在为App Store导出时，请关闭Xcode UI中的“管理版本和构建编号”选项。如果您希望保持此选项开启，请注意，SDK将无法跟踪嵌入式SDKs框架的版本。

页面视图如何自动跟踪

我们使用方法交换来在每个新的视图控制器呈现时自动触发访问事件，除非

• 视图控制器是用于协调“内容”视图控制器的已知“chrome”之一，即UINavigationController、UISplitViewController、UIPageViewController和UITabBarController之一。
• 视图控制器正在显示系统弹出窗口，即UIAlertView、UIActionSheet、UIAlertController或_UIPopoverView。
• 视图控制器、其视图或它附加的窗口是Apple私有类的实例，即类名带_前缀且来自系统框架的类。这可以防止许多屏幕上的系统配件生成虚假的页面视图。
• 视图控制器附加的窗口的类是从系统框架继承的UIWindow子类，即该窗口不是一个普通应用程序窗口。某些屏幕上的系统配件，如系统的自动完成单词拾取器，否则也会触发事件。

这些访问事件对所有跟踪器都是可用的，并且可以从中找到事件状态的currentPage属性中传递给RAnalyticsTracker#processEvent:state:的事件主题视图控制器。

RAT跟踪器还忽略那些没有标题、没有导航项标题，并且在调用-viewDidLoad时在它们的视图层次结构中未能找到任何webview URL的视图控制器，除非它们已被应用程序或应用程序中嵌入的框架之一所继承。这会过滤掉提供应用程序中访问页面无信息的事件，例如报道页面名为UIViewController的事件。对于具有标题、导航项标题或URL的视图控制器，库还设置了发送到RAT的pv事件的cp.title和cp.url字段。

使用RAT跟踪搜索结果

以下代码展示了您可以发送到RAT的事件示例，用于跟踪搜索页面上显示哪些搜索结果。它使用标准RAT事件 pv，与前面的示例一样，以及多个标准RAT参数。使用的参数有

RAnalyticsRATTracker.shared().event(eventType: "pv",
parameters:["pgn": "shop_search",
"pgt": "search",
"lang": "English",
"sq": "search query",
"oa": "a",
"esq": "excluded query",
"genre": "category",
"tag": ["tag 1", "tag 2"]]).track()

监控RAT流量

您可以通过监听 RAnalyticsWillUploadNotification、RAnalyticsUploadFailureNotification 和 RAnalyticsUploadSuccessNotification 通知，来监控跟踪网络的流量。

验证成功集成

如果SDK正确集成，发送给RAT的登录用户的事件将包含包含用户成员标识符的 easyid 字段。有关如何检查发送给RAT的事件的指南，请参阅此处。

核心电话值跟踪：CTCarrier弃用

我们使用CTCarrier API来跟踪值

• carrierName
• mobileCountryCode
• mobileNetworkCode
• isoCountryCode
• allowsVOIP

自iOS 16.4起，CTCarrier是一个已弃用的API（iOS 16.4发行说明），并且在未来的更新中将会被去除，没有任何替代品。作为弃用过程的一部分，《CTCarrier》值将始终返回空字符串或65535作为默认值。

CTCarrier已被用来提供mcn，mcnd，simopn和simop值。根据《CTCarrier》的变化，我们将停止对CTCarrier API的支持，并在苹果在未来iOS更新中从《核心电话》中移除此API后将其删除。

mcn，mcnd，simopn和simop值在CTCarrier弃用前后示例