:::tip 这是iOS SDK新版集成文档，包含： * [iOS SDK 集成](/docs/84129/1587783)（本篇文档） * [iOS SDK API 说明](/docs/84129/1587781) * [iOS SDK 集成场景实践](/docs/84129/1587779) * [iOS 接入隐私配置 PrivacyInfo.xcprivacy](/docs/84129/1587782) * [参考：iOS SDK 发布日志及升级指南](/docs/84129/1587777) * [参考：iOS SDK 集成 FAQ](/docs/84129/1587774) 如果想继续查看旧版文档，请点击这个链接：[iOS SDK集成](/docs/84129/1261736) ::: # 文档导读下图为您概要介绍 SDK 集成相关文档的组织思路，您可参考以下导读示意图了解文档结构，查阅对应文档完成集成操作。 ![Image](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/0736e6ec3b2343a8a7bcdd970382d83c~tplv-goo7wpa0wc-image.image =4298x) # 埋点规划在进行 SDK 集成前，您需结合您的业务分析情况先进行埋点规划，明确出待分析的业务指标中可能需要埋点的事件有哪些、属性有哪些等。进行埋点规划时，您需了解一些基本概念和 DataFinder 为您预置提供的埋点事件和属性、DataFinder 的用户标识逻辑等前置信息，结合 DataFinder 为您提供的能力进行埋点规划。 ## 基本概念 | | | | | \ |基本概念 |概念说明 |埋点规划与 SDK 集成要点 |详细指导文档 | |---|---|---|---| | | | | | \ |事件、事件属性、事件公共属性、用户属性 |DataFinder 的用户行为数据分析是基于事件+用户模型的分析模型。 |\ | | |\ | |* 事件&事件属性：用户的某一种或一类行为称之为“事件”，事件属性即事件触发时同步采集的事件发生的形式、位置等用来描述事件的信息。例如，某个用户购买了某个商品，则该用户的行为事件为“购买”，事件属性为“商品名称”、“商品分类”、“支付金额”等。 |\ | |* 事件公共属性：指不与某个事件强关联、在多个或所有事件中都共同存在的**不频繁变化的属性**，例如，应用的版本号、设备信息等。 |\ | |* 用户&用户属性：用户指的是事件行为的发生主体人。用户属性指的是用户自身状态的属性（与行为无关，例如年龄、性别等）或与行为有关但不常变化的用户相关属性（如 VIP 等级、注册时间等）。 |您需根据业务分析需要，规划好待采集的事件、事件属性、用户属性有哪些、类型是什么，进行 SDK 集成时 |详细概念介绍请参见[数据模型](/docs/84129/1261511)。 | | | | | | \ |埋点、全埋点、自定义埋点 |* 埋点：通过 SDK 的开发，将事件逻辑写入代码的过程，称之为**埋点**。DataFinder 为您提供了预置事件及事件属性，这类事件及事件属性无需您手动埋点，只需打开采集开关即可。 |\ | |* 全埋点：是 DataFinder 提供的预置事件和事件属性的一种，在 DataFinder 中，采集的全埋点事件为 bav2b_click 按钮点击， bav2b_page 页面浏览。不需要研发额外投入，但会以上报大量数据为代价，并且只可以采集简单的 PV、UV，对于丰富业务数据的采集显得有些‘力不从心’。 |\ | |* 代码埋点：代码埋点指的是开发工程师，按照业务个性化需求，人工写入代码中以实现数据采集逻辑。采集范围广、应用灵活。但需要研发投入，且需要一定的技术能力。 |通常建议您结合 DataFinder 提供的预置事件/属性和自定义埋点进行埋点规划。 |[埋点、全埋点](/docs/84129/1261517) | ## 了解数据上报要求（格式、数量限制等）进行埋点规划时，您需明确清楚需采集上报的事件、属性的数据格式要求，以及采集上报的一些限制要求，避免后续因为数据格式等不满足要求，进而导致数据采集后无法入库、后续无法查询分析。 SDK上报的数据通常有固定的格式，主要包括 header、事件两个部分。 | | | | \ |字段 |作用 |iOS 端数据示例 | |---|---|---| | | | | \ |header |存放事件公共属性。 |\ | |app_id、os_name 这些都是预置的，会直接放在 header下，如果是您自定义设置的事件公共属性，会放到header.custom 下。 |```JSON |\ | | |{ |\ | | | "event_v3" : [ |\ | | | { |\ | | | "local_time_ms" : 1749023627671, |\ | | | "$user_unique_id_type" : null, |\ | | | "params" : { |\ | | | "_additional" : "ddd", |\ | | | "send_times" : 3, |\ | | | "session_no" : 1, |\ | | | "session_start_time" : "2025-06-04 15:50:47", |\ | | | "$app_version" : "1.0", |\ | | | "current_duration" : 60 |\ | | | }, |\ | | | "event" : "play_session", |\ | | | "user_unique_id" : null, |\ | | | "ab_sdk_version" : "1314,1328", |\ | | | "track_id" : "E957BFFB-CF87-49E2-8F0E-305DBE8DD5C6", |\ | | | "ssid" : "fc351da8-ddff-4ae3-9878-2c380b6796e2", |\ | | | "session_id" : "803E519E-D828-48C1-8F46-2C89CA9BC90A", |\ | | | "nt" : 4, |\ | | | "datetime" : "2025-06-04 15:53:47", |\ | | | "tea_event_index" : 24 |\ | | | }, |\ | | | { |\ | | | "local_time_ms" : 1749023606322, |\ | | | "$user_unique_id_type" : null, |\ | | | "params" : { |\ | | | "page_title" : "导航首页", |\ | | | "referrer_page_path" : "", |\ | | | "refer_page_key" : "BDAutoTrackDevNetworkController", |\ | | | "is_back" : 1, |\ | | | "page_key" : "BDTestIntroducerViewController", |\ | | | "refer_page_title" : "网络", |\ | | | "$app_version" : "1.0", |\ | | | "_additional" : "ddd" |\ | | | }, |\ | | | "event" : "bav2b_page", |\ | | | "user_unique_id" : null, |\ | | | "ab_sdk_version" : "1314,1328", |\ | | | "track_id" : "0A944C1F-5280-409C-9645-44B84E7CDBAF", |\ | | | "ssid" : "fc351da8-ddff-4ae3-9878-2c380b6796e2", |\ | | | "session_id" : "803E519E-D828-48C1-8F46-2C89CA9BC90A", |\ | | | "nt" : 4, |\ | | | "datetime" : "2025-06-04 15:53:26", |\ | | | "tea_event_index" : 23 |\ | | | } |\ | | | ], |\ | | | "time_sync" : { |\ | | | "local_time" : 1749023569, |\ | | | "server_time" : 1749023569 |\ | | | }, |\ | | | "magic_tag" : "ss_app_log", |\ | | | "header" : { |\ | | | "app_version_minor" : "1", |\ | | | "region" : "CN", |\ | | | "access" : "WIFI", |\ | | | "os_version" : "18.4", |\ | | | "device_model" : "arm64", |\ | | | "user_unique_id_type" : null, |\ | | | "platform" : "ios", |\ | | | "app_name" : "applog_oc_demo", |\ | | | "vendor_id" : "FA190FD0-2293-4025-B8E6-A7E015CD579D", |\ | | | "sdk_version" : 61703, |\ | | | "custom" : { |\ | | | "Dictioanry" : { |\ | | | "A" : "B" |\ | | | }, |\ | | | "Array" : [ |\ | | | "123", |\ | | | "34" |\ | | | ], |\ | | | "level" : 0, |\ | | | "boolValue" : true, |\ | | | "intValue" : 1, |\ | | | "touch_point" : "iOS APP端" |\ | | | }, |\ | | | "display_name" : "ObjCExample", |\ | | | "channel" : "App Store", |\ | | | "sdk_lib" : "ios", |\ | | | "app_region" : "CN", |\ | | | "ab_sdk_version" : "1314,1328", |\ | | | "user_agent" : "ObjCExample 1.0 rv:1 (iphone; iOS 18.4; en_CN)", |\ | | | "idfa" : "00000000-0000-0000-0000-000000000000", |\ | | | "device_platform" : "iphone", |\ | | | "install_id" : "722808630681020", |\ | | | "user_unique_id" : null, |\ | | | "os" : "iOS", |\ | | | "tz_name" : "Asia\/Shanghai", |\ | | | "tz_offset" : 28800, |\ | | | "app_language" : "en", |\ | | | "is_upgrade_user" : false, |\ | | | "aid" : "418165", |\ | | | "ssid" : "fc351da8-ddff-4ae3-9878-2c380b6796e2", |\ | | | "package" : "com.data.extracker", |\ | | | "is_jailbroken" : false, |\ | | | "language" : "zh", |\ | | | "sdk_version_code" : 10061703, |\ | | | "bd_did" : "LIDKFFMUEAV5HTDDPHFYUGDUCXKMUT7U2B3IJOD5GVACVKXUVPKQ01", |\ | | | "app_version" : "1.0", |\ | | | "resolution" : "1206*2622", |\ | | | "timezone" : 8 |\ | | | }, |\ | | | "local_time" : 1749023629 |\ | | |} |\ | | |``` |\ | | | | | | |^^| \ |事件 |存放事件及事件属性。 |\ | |事件分为 launch、terminate、event_v3。 |\ | |其中 launch、terminate 为预置的启动、退出事件。 |\ | |event_v3 存放自定义事件、page 事件等，每个 event_v3 类型事件都有 event、params、local_time_ms、session_id 几个字段，其中local_time_ms、session_id 是SDK自动产生的，而event、params 是业务设置的，event 是事件名，params 存放的是事件属性（值是 JSON 对象进行了序列化操作）。 | | 其中，需要上报自定义事件、自定义属性时，您需确保事件和属性的数据格式符合要求，当前 DataFinder 支持的数据格式要求和数据上报的限制请参见[支持的数据格式与事件/属性分类](/docs/84129/1261719)。常见问题： * 事件属性数据类型传输错误，需要修改怎么办？[Q1：事件属性数据类型传输错误，需要修改怎么办？](/docs/84129/1261719#q1：事件属性数据类型传输错误，需要修改怎么办？) * 各端数据类型传输不一致，系统如何处理？如何修改？[Q2：各端数据类型传输不一致，系统如何处理？如何修改？](/docs/84129/1261719#q2：-各端数据类型传输不一致，系统如何处理？如何修改？) ## 了解用户标识逻辑进行埋点规划时，您需要了解 DataFinder 的用户标识逻辑，用于结合自身业务的用户标识逻辑进而最终统一用户的标识数据来源。DataFinder 默认以**用户**作为统计分析的对象，默认使用 SSID 作为用户唯一标识 ID 来计算指标，此时用户的 SSID 就是默认的统计口径。当您的分析对象为用户时，建议保持默认统计口径 SSID，DataFinder 可通过 ID_Mapping 将用户的device_id、user_unique_id 等进行 mapping 后，尽量通过一个 SSID 还原一个真实的用户个体。 * **device_id**：可作为设备的唯一 id，多为无法获取用户实名 id的场景下使用。 * **user_unique_id**：为登录态用户标识，多为在能获取用户实名 ID 场景下使用，一般情况直接使用产品业务中使用的用户标识，比如登录账号。当 user_unique_id 未设定时，在 SaaS 版本中，系统会自动使用 device_id 替代。 * **SSID**：为 DataFinder 的用户统计口径 ID，与设备标识 device_id、登录态用户标识 user_unique_id 互相 Mapping，能保证用户匿名和实名状态下的 ID 统一。三类 ID 的 mapping 逻辑和更多关于用户标识的介绍详情请参见[支持的用户唯一标识](/docs/84129/1261731)。 :::tip * 如果您的业务中用户实名 ID 有多种 ID 类型，例如，可通过账号 ID、用户手机号等多种 ID 类型来标注用户的实名信息，您也可以使用多ID类型功能，详情请参见[使用多ID类型](/docs/84129/1359449)。 ::: ## 了解客户端支持的预置事件和属性如上文所述，大部分业务分析场景中，您需要结合自身业务特性进行自定义埋点的规划和集成，在此之前，您可以先了解下当前 DataFinder 已为您提供的预置事件、预置属性有哪些，结合已有的预置事件和属性能力，进一步规划自定义代码埋点的需求。 * App 端支持的预置事件和属性列表请参见[Android端预置事件及属性](/docs/84129/1261724)。 * 同时您还需关注当前禁用的预置属性列表，后续规划自定义埋点及属性时需避免与禁用属性同名，否则会导致数据无法正常上报，详情请参见[禁用属性列表](/docs/84129/1261730)。 ## 梳理埋点需求设计埋点方案 * [如何梳理需求](https://www.volcengine.com/docs/84129/1261519) * [如何设计埋点采集方案](https://www.volcengine.com/docs/84129/1261522) * [指标体系demo](https://bytedance.larkoffice.com/sheets/shtcng6Cp2HHiTGGA2LPIf3Rl5e) * [埋点方案模板](https://www.volcengine.com/docs/84129/1261523) # 准备工作 ## 步骤1（可选）：创建埋点需求/录入自定义埋点完成埋点规划后，建议您根据规划将埋点需求创建再 DataFinder 的需求管理页面，并将自定义埋点先录入 DataFinder 完成自定义埋点在 DataFinder 元数据的入库。 * 埋点需求管理：您可以通过 DataFinder 的埋点需求管理功能来管理埋点需求，后续可在埋点需求管理页面中持续维护和管理需求，提高管理效率。创建埋点需求管理的操作请参见[需求管理](/docs/84129/1554708)。 * 自定义埋点录入：您可以根据埋点规划，先将自定义埋点创建录入至 DataFinder 的元数据，操作详情请参见[新增事件](/docs/84129/1261662#_2-1-新增事件)、[新增事件属性](/docs/84129/1261664#_2-1-新增事件属性)、[新增用户属性](/docs/84129/1398945#533b53ea)。 ## 步骤2：获取APPID/APP Url 进行SDK集成前，您需要先获取在DataFinder上创建应用时，DataFinder生成的应用标识（APPID 或 APP Url），用于后续SDK集成时配置。 :::warning * SaaS-云原生环境中，iOS SDK 自6.17.4版本开始支持安全模式，即同时支持使用APPID 或 APP Url进行SDK集成配置，您可参考以下方式提前获取待集成SDK的应用APPID 或 APP Url，APP Url可视为加密后的APPID，配置过程更加安全。 * 其他场景暂不支持使用APP Url进行配置，您可获取并使用APPID进行SDK集成配置。 ::: * SaaS-云原生场景下，您可以在「项目中心」>「项目管理」>「项目详情」中找到对应应用，单击“接入数据”，在应用详情中查看应用的应用ID（APPID）、APP Url，详情请参见[项目管理](/docs/84129/1261713)。 ![Image](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/08ce71b4135c489e9b374c8feb10fcf3~tplv-goo7wpa0wc-image.image =1443x) * SaaS-非云原生场景下，您可以在「集团设置」>「应用列表」中到对应应用，单击对应应用的“详情”，在-应用详情中查看应用的应用ID（APPID），详情请参见[应用列表](/docs/84129/1261706)。 ![Image](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/ececf40ef47948a6a6b068d7010b8707~tplv-goo7wpa0wc-image.image =1691x) ## 步骤3：获取上报地址进行数据接入上报时，您需要根据当前的环境类型和端类型确认您的数据上报地址。如果上报地址设置错误，后续会导致您无法正常上报、查询到数据。 ### 获取数据上报地址 :::warning * 请在上报数据前，务必确认您当前使用的环境类型，根据环境类型配置上报地址。查看当前的环境类型请参见[SaaS云原生/非云原生&私有化环境](/docs/84129/1261497)。 * 如果您使用的是 SaaS-云原生环境，您也需确认您的服务所在的地域，根据所在地域配置上报地址（通常您的服务会在华北2-北京地域，部分用户可能会使用其他地域）。SaaS-云原生用户查看服务所在地域请参见[支持的地域](/docs/84129/1527757)。 ::: #### SaaS-云原生 & SaaS-非云原生 | | | | | | \ |端类型 |SaaS-云原生环境 |\ | |（国内：华北2-北京&华南1-广州） |SaaS-云原生环境 |\ | | |（海外：亚太东南-柔佛） |SaaS-非云原生环境国内环境 |SaaS-非云原生海外BytePlus环境 |\ | | | | |（以下 SG 指新加坡） | |---|---|---|---|---| | | | | | | \ |iOS |* SaaS-云原生（华北）：https://gator.volces.com |\ | |* SaaS-云原生（华南）： |\ | | https://gator.uba.cn-guangzhou.volces.com |* https://gator.uba.ap-southeast-1.volces.com |引入：'Host/CN' 后，无需配置 |引入：'Host/SG' 后，无需配置 | #### 私有化环境私有化部署场景下，您需要获取部署私有化环境时，自行规划配置的数据上送地址。如您不清楚此地址，请联系您的项目经理或客户成功经理。 # 集成SDK ## （可选）下载示例 demo 以下为您提供了一个简单的 iOS 项目作为示例 demo，下文的 SDK 集成操作指导也基于此 demo，您可先下载 demo 文件用于学习了解 iOS SDK 的集成操作。 ## step1：添加SDK所需依赖 | | | \ |操作指导 |操作录屏 | |---|---| | | | \ |使用CocoaPods引入source源，在Podfile中，添加source源。 |\ |```Ruby |\ |source 'https://github.com/volcengine/volcengine-specs.git' |\ |``` |\ | |\ |在Podfile中，引入SDK，并执行`pod install --repo-update`更新Pods。 |\ |```Ruby |\ |pod 'RangersAppLog', '6.17.6', |\ | :subspecs => [ |\ | 'Core', |\ | # 其他可选的子模块 |\ | 'UITracker' #全埋点功能（可选） |\ | # ...更多可选的子模块 |\ | ] |\ |``` |\ | | |\ | | |\ | | | 子模块说明 | | | | \ |**子模块** |**说明** |**备注** | |---|---|---| | | | | \ |Core |核心模块，**必须** | | | | | | \ |Host/CN |SaaS国内非云原生，**可选** |在SaaS国内非云原生环境下需引入这个子模块，其他环境不需要 | | | | | \ |Host/SG |SaaS海外非云原生，**可选** |在SaaS国外非云原生环境下需引入这个子模块，其他环境不需要 | | | | | \ |UITracker |全埋点功能，**可选** |需要全埋点功能时需引入这个子模块 | | | | | \ |Log |圈选功能和实时埋点检测，**可选** |希望进行埋点实时检测或圈选功能时，需引入这两个子模块，实时埋点检测和圈选功能仅在开发阶段使用，上线后需要移除这两个子模块 | | | |^^| \ |Picker |圈选功能，**可选** | | | | | | \ |Unique |采集IDFA，**可选** |希望在授权后采集IDFA，需引入这个子模块，**该库仅在额外购买 Tracer 做归因业务时需要** | | | | | \ |DevTools |DevTools组件，**可选** |DevTools是辅助开发者或测试人员进行应用内埋点验证和SDK接入问题排查的组件 | | | | | \ |Exception |崩溃采集，**可选** |目前仅支持采集 NSException 崩溃 | | | | | \ |DeviceOrientation |屏幕方向采集，**可选** |版本6.11.0+后开始支持 | | | | | \ |Location |采集GPS，**可选** |需要定位权限，也可以选择手动传入经纬度坐标，从而不集成该库 | | | | | \ |Encryptor/SM2 |国密SM2加密，**可选** |仅私有化版本支持 | | | | | \ |Exposure |组件曝光，**可选** |用于组件曝光事件 | 各环境配置示例 | | | | \ |云原生环境 |私有化 |非云原生环境 | |---|---|---| | | | | \ |```Ruby |\ |source 'https://github.com/volcengine/volcengine-specs.git' |\ | |\ |# target 'TestDemo' do |\ | # ... |\ | pod 'RangersAppLog', '6.17.6', |\ | :subspecs => [ |\ | 'Core', |\ | 'UITracker' #全埋点功能（可选） |\ | ] |\ |# end |\ |``` |\ | |\ | |```Ruby |\ | |source 'https://github.com/volcengine/volcengine-specs.git' |\ | | |\ | |# target 'TestDemo' do |\ | | # ... |\ | | pod 'RangersAppLog', '6.17.6', |\ | | :subspecs => [ |\ | | 'Core', |\ | | 'UITracker' #全埋点功能（可选） |\ | | ] |\ | |# end |\ | |``` |\ | | |```Ruby |\ | | |source 'https://github.com/volcengine/volcengine-specs.git' |\ | | | |\ | | |# target 'TestDemo' do |\ | | | # ... |\ | | | pod 'RangersAppLog', '6.17.6', |\ | | | :subspecs => [ |\ | | | 'Core', |\ | | | 'Host/CN', # 非云原生-国内 |\ | | | # 'Host/SG', # 非云原生-海外 |\ | | | 'UITracker' #全埋点功能（可选） |\ | | | ] |\ | | |# end |\ | | |``` |\ | | | | ## step2：初始化 SDK 通常建议集成时参考以下流程： | | \ |初始化 SDK ---> 上报事件 ---> 设置用户登录态 ---> 验证上报 | |---| | | \ |以下为一个简单的初始化 SDK 代码示例，您可通过此示例来快速了解 SDK 集成时的代码、涉及的初始化接口、典型的配置参数等，后续步骤中会为您逐步介绍 SDK 集成的详细操作要点。 |\ |`Objective-C`请参考： |\ |```objectivec |\ |#import |\ |#import |\ |// 若使用 Unique 子库，则需要依赖该头文件 |\ |// #import |\ | |\ |- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { |\ | |\ | /* 初始化SDK开始 */ |\ | BDAutoTrackConfig*config = [BDAutoTrackConfig configWithAppID:@"{{APPID}}" launchOptions:launchOptions]; |\ | // 设置渠道，iOS一般默认App Store渠道 |\ | config.channel = @"App Store"; |\ | |\ | // 设置数据上送地址，您需根据使用的DataFinder服务所在地域配置上送地址 |\ | config.serviceVendor = BDAutoTrackServiceVendorPrivate; |\ | BDAutoTrackRequestHostBlock block = |\ | ^NSString *(BDAutoTrackServiceVendor vendor, BDAutoTrackRequestURLType requestURLType) { |\ | return @"https://****.****.com"; |\ | }; |\ | [BDAutoTrack setRequestHostBlock:block]; |\ | |\ | config.autoTrackEnabled = YES; // 全埋点开关，YES开启，NO关闭 |\ | config.showDebugLog = NO; // YES:开启日志，NO:关闭日志 |\ | config.logNeedEncrypt = YES; // 加密开关，YES开启，NO关闭 |\ | [BDAutoTrack sharedTrackWithConfig:config]; |\ | /* 初始化SDK结束 */ |\ | |\ | // 若使用 Unique 子库，则需要配置 idfa 专用域名 |\ | // [BDAutoTrack.sharedTrack setRequestIDFAHostBlock:^NSString * _Nullable(BDAutoTrackServiceVendor _Nonnull vendor, BDAutoTrackRequestURLType requestURLType) { |\ | // return @"https://gator-tracking.datafinder.volces.com"; |\ | // }]; |\ | |\ | // 授权后 |\ | [[BDAutoTrack sharedTrack] startTrack]; //SDK启动 |\ | |\ | return YES; |\ |} |\ |``` |\ | |\ |```objectivec |\ |// 上报事件以及设置登录态 |\ |#import |\ | |\ |// ... |\ | |\ |@implementation ViewController |\ | |\ |- (void)viewDidLoad { |\ | [super viewDidLoad]; |\ | // 上报事件 |\ | [BDAutoTrack eventV3:@"event_test" params:@{@"key_string": @"value_string", @"key_int": @(10)}]; |\ | |\ | // 设置登录态, 版本6.13.0+ |\ | [[BDAutoTrack sharedTrack] setCurrentUserUniqueID:@"当前登陆态UUID"]; |\ |} |\ | |\ |@end |\ |``` |\ | | | | \ |`Swift`请参考： |\ |```Swift |\ |import RangersAppLog |\ | |\ |func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { |\ | |\ | /* 初始化SDK开始 */ |\ | let config = BDAutoTrackConfig(appID: "{{APPID}}") |\ | // 设置渠道，iOS一般默认App Store渠道 |\ | config.channel = "App Store" |\ | // 设置数据上送地址，您需根据使用的DataFinder服务所在地域配置上送地址 |\ | config.serviceVendor = .private |\ | BDAutoTrack.setRequestHostBlock {(vendor: BDAutoTrackServiceVendor, requestURLType:BDAutoTrackRequestURLType) -> String? in |\ | return "https://gator.volces.com" |\ | } |\ | |\ | config.autoTrackEnabled = true // 全埋点开关，true开启，false关闭 |\ | config.showDebugLog = false // true:开启日志，需要参考4.3设置Logger，false:关闭日志 |\ | config.logNeedEncrypt = true // 加密开关，true开启，false关闭 |\ | BDAutoTrack.sharedTrack(with: config) |\ | /* 初始化SDK结束 */ |\ | |\ | // 若使用 Unique 子库，则需要配置 idfa 专用域名 |\ | // BDAutoTrack.shared().setRequestIDFAHostBlock {(vendor: BDAutoTrackServiceVendor, requestURLType:BDAutoTrackRequestURLType) -> String? in |\ | // return "https://gator-tracking.datafinder.volces.com" |\ | // } |\ | |\ | BDAutoTrack.shared().start() //SDK启动 |\ | |\ | return true |\ |} |\ |``` |\ | |\ |```Swift |\ |import RangersAppLog |\ | |\ |// ... |\ | |\ |class ViewController: UIViewController { |\ | |\ | override func viewDidLoad() { |\ | super.viewDidLoad() |\ | // 上报事件 |\ | BDAutoTrack.eventV3("event", params: ["key_string": "value_string", "key_int": 10]) |\ | |\ | // 设置登录态, 版本6.13.0+ |\ | BDAutoTrack.setCurrentUserUniqueID("{{USER_UNIQUE_ID}}") |\ | } |\ |} |\ |``` |\ | |\ | | 以下示例，为您逐步演示大部分场景下初始化SDK的代码接入。 ### 导入并初始化 | | | \ |操作指导 |操作录屏 | |---|---| | | | \ |`Objective-C`请参考： |\ |```objectivec |\ |#import |\ |#import |\ | |\ |- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { |\ | |\ | /* 初始化SDK开始 */ |\ | BDAutoTrackConfig*config = [BDAutoTrackConfig configWithAppID:@"{{APPID}}" launchOptions:launchOptions]; |\ | // 设置渠道，iOS一般默认App Store渠道 |\ | config.channel = @"App Store"; |\ | |\ | // 设置数据上送地址，您需根据使用的DataFinder服务所在地域配置上送地址，详情见上文获取数据上送地址章节 |\ | config.serviceVendor = BDAutoTrackServiceVendorPrivate; |\ | BDAutoTrackRequestHostBlock block = |\ | ^NSString *(BDAutoTrackServiceVendor vendor, BDAutoTrackRequestURLType requestURLType) { |\ | return @"https://****.****.com"; |\ | }; |\ | [BDAutoTrack setRequestHostBlock:block]; |\ | |\ | config.autoTrackEnabled = YES; // 全埋点开关，YES开启，NO关闭 |\ | config.showDebugLog = NO; // YES:开启日志，NO:关闭日志 |\ | config.logNeedEncrypt = YES; // 加密开关，YES开启，NO关闭 |\ | [BDAutoTrack sharedTrackWithConfig:config]; |\ | /* 初始化SDK结束 */ |\ | |\ | // 授权后 |\ | [[BDAutoTrack sharedTrack] startTrack]; //SDK启动 |\ | |\ | return YES; |\ |} |\ |``` |\ | |\ |`Swift`请参考： |\ |```Swift |\ |import RangersAppLog |\ | |\ |func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { |\ | |\ | /* 初始化SDK开始 */ |\ | let config = BDAutoTrackConfig(appID: "{{APPID}}") |\ | // 设置渠道，iOS一般默认App Store渠道 |\ | config.channel = "App Store" |\ | // 设置数据上送地址，您需根据使用的DataFinder服务所在地域配置上送地址 |\ | config.serviceVendor = .private |\ | BDAutoTrack.setRequestHostBlock {(vendor: BDAutoTrackServiceVendor, requestURLType:BDAutoTrackRequestURLType) -> String? in |\ | return "https://****.****.com" |\ | } |\ | |\ | config.autoTrackEnabled = true // 全埋点开关，true开启，false关闭 |\ | config.showDebugLog = false // true:开启日志，需要参考4.3设置Logger，false:关闭日志 |\ | config.logNeedEncrypt = true // 加密开关，true开启，false关闭 |\ | BDAutoTrack.sharedTrack(with: config) |\ | /* 初始化SDK结束 */ |\ | |\ | BDAutoTrack.shared().start() //SDK启动 |\ | |\ | return true |\ |} |\ |``` |\ | | |\ | | |\ | | | ### **关于各环境上报域名示例** 设置数据上报域名前，您需要先明确您使用的环境和所在的地域，根据实际情况设置上报域名。确认您当前使用的环境类型请参见：[SaaS云原生/非云原生&私有化环境](/docs/84129/1261497)。 | | | | \ |云原生环境 |私有化环境 |非云原生环境 | |---|---|---| | | | | \ |* 云原生（华北：北京）：https://gator.volces.com |\ |* 云原生（华南：广州）：https://gator.uba.cn-guangzhou.volces.com |\ |* 云原生（海外：亚太东南-柔佛）：https://gator.uba.ap-southeast-1.volces.com |\ | |\ |```objectivec |\ |// ... |\ |- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { |\ | |\ | /* 初始化SDK开始 */ |\ | BDAutoTrackConfig*config = [BDAutoTrackConfig configWithAppID:@"{{APPID}}" launchOptions:launchOptions]; |\ | // 设置渠道，iOS一般默认App Store渠道 |\ | config.channel = @"App Store"; |\ | |\ | // 设置数据上送地址，您需根据使用的DataFinder服务所在地域配置上送地址 |\ | config.serviceVendor = BDAutoTrackServiceVendorPrivate; |\ | BDAutoTrackRequestHostBlock block = |\ | ^NSString *(BDAutoTrackServiceVendor vendor, BDAutoTrackRequestURLType requestURLType) { |\ | // 云原生-（华北：北京） |\ | return @"https://gator.volces.com"; |\ | |\ | // 云原生-（华南：广州） |\ | // return @"https://gator.uba.cn-guangzhou.volces.com"; |\ | // 云原生-（海外：亚太东南-柔佛） |\ | // return @"https://gator.uba.ap-southeast-1.volces.com"; |\ | }; |\ | [BDAutoTrack setRequestHostBlock:block]; |\ | |\ | config.autoTrackEnabled = YES; // 全埋点开关，YES开启，NO关闭 |\ | // ... |\ | |\ | return YES; |\ |} |\ |``` |\ | |```objectivec |\ | |// ... |\ | |- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { |\ | | |\ | | /* 初始化SDK开始 */ |\ | | BDAutoTrackConfig*config = [BDAutoTrackConfig configWithAppID:@"{{APPID}}" launchOptions:launchOptions]; |\ | | // 设置渠道，iOS一般默认App Store渠道 |\ | | config.channel = @"App Store"; |\ | | |\ | | // 设置私有化部署数据上送地址，替换{{REPORT_URL}} 例如 https://yourdomain.com，注意域名后不要加“/” |\ | | config.serviceVendor = BDAutoTrackServiceVendorPrivate; |\ | | BDAutoTrackRequestHostBlock block = |\ | | ^NSString *(BDAutoTrackServiceVendor vendor, BDAutoTrackRequestURLType requestURLType) { |\ | | return @"{{REPORT_URL}}"; |\ | | }; |\ | | [BDAutoTrack setRequestHostBlock:block]; |\ | | |\ | | config.autoTrackEnabled = YES; // 全埋点开关，YES开启，NO关闭 |\ | | // ... |\ | | |\ | | return YES; |\ | |} |\ | |``` |\ | | |```objectivec |\ | | |// ... |\ | | |- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { |\ | | | |\ | | | /* 初始化SDK开始 */ |\ | | | BDAutoTrackConfig*config = [BDAutoTrackConfig configWithAppID:@"{{APPID}}" launchOptions:launchOptions]; |\ | | | // 设置渠道，iOS一般默认App Store渠道 |\ | | | config.channel = @"App Store"; |\ | | | |\ | | | // 设置数据上送地址 |\ | | | // 国内环境请配置为BDAutoTrackServiceVendorCN |\ | | | config.serviceVendor = BDAutoTrackServiceVendorCN; |\ | | | // 海外BytePlus环境请配置为BDAutoTrackServiceVendorSG |\ | | | // config.serviceVendor = BDAutoTrackServiceVendorSG; |\ | | | |\ | | | config.autoTrackEnabled = YES; // 全埋点开关，YES开启，NO关闭 |\ | | | // ... |\ | | | |\ | | | return YES; |\ | | |} |\ | | |``` |\ | | | | ### 上报自定义事件根据埋点规划，如果需要采集上报自定义事件，您可以使用“eventV3”设置自定义事件名和事件属性。 | | | \ |操作指导 |操作录屏 | |---|---| | | | \ |`Objective-C`请参考： |\ |```objectivec |\ |#import |\ | |\ |// ... |\ | |\ |@implementation ViewController |\ | |\ |- (void)viewDidLoad { |\ | [super viewDidLoad]; |\ | // 上报事件 |\ | [BDAutoTrack eventV3:@"event_test" params:@{@"key_string": @"value_string", @"key_int": @(10)}]; |\ |} |\ | |\ |@end |\ |``` |\ | |\ |`Swift`请参考： |\ |```Swift |\ |import RangersAppLog |\ | |\ |// ... |\ | |\ |class ViewController: UIViewController { |\ | |\ | override func viewDidLoad() { |\ | super.viewDidLoad() |\ | // 上报事件 |\ | BDAutoTrack.eventV3("event", params: ["key_string": "value_string", "key_int": 10]) |\ | } |\ |} |\ |``` |\ | | |\ | | |\ | | | * 涉及核心API： * eventV3：使用 eventV3 方法可以上报自定义事件。该方法支持单个事件方式。 ### 设置用户登录态如果需要设置用户登录态，可以使用setCurrentUserUniqueID 方法设置 user_unique_id 属性。通常对于需要用户实名登录时，业务上会使用一个 ID 来唯一标识这个用户，您可以通过 setCurrentUserUniqueID 方法上报对应的业务的用户标识 ID。通常这个取值可以通过业务接口获取，或者直接读取已有的固定用户标识 ID 值。 | | | \ |操作指导 |操作录屏 | |---|---| | | | \ |`Objective-C`请参考： |\ |```objectivec |\ |#import |\ | |\ |// ... |\ | |\ |@implementation ViewController |\ | |\ |- (void)viewDidLoad { |\ | [super viewDidLoad]; |\ | // ... |\ | // 设置登录态, 版本6.13.0+ |\ | [[BDAutoTrack sharedTrack] setCurrentUserUniqueID:@"当前登陆态UUID"]; |\ |} |\ | |\ |@end |\ |``` |\ | |\ |`Swift`请参考： |\ |```Swift |\ |import RangersAppLog |\ | |\ |// ... |\ | |\ |class ViewController: UIViewController { |\ | |\ | override func viewDidLoad() { |\ | super.viewDidLoad() |\ | // 设置登录态, 版本6.13.0+ |\ | BDAutoTrack.setCurrentUserUniqueID("{{USER_UNIQUE_ID}}") |\ | } |\ |} |\ |``` |\ | | |\ | | |\ | | | * 涉及核心API： * 您可以通过 setCurrentUserUniqueID 方法来设置用户的业务标识 ID——user_unique_id，设置前您需要先了解 DataFinder 的用户标识逻辑（详情请参见[支持的用户唯一标识](/docs/84129/1261731)）。 ## step3：验证上报 ### 使用 iOS Devtools 调试工具 1. 引入Devtools子模块，subspecs添加`DevTools` ```Ruby pod 'RangersAppLog', 'SDK-VERSION', :subspecs => [ # ... 'DevTools' ] ``` 2. 初始化时开启DevTools ```objectivec #import // ... #import - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { /* 初始化SDK开始 */ BDAutoTrackConfig*config = [BDAutoTrackConfig configWithAppID:@"{{APPID}}" launchOptions:launchOptions]; // ... // 配置开启DevTool功能 config.devToolsEnabled = YES; // ... [BDAutoTrack sharedTrackWithConfig:config]; /* 初始化SDK结束 */ // 授权后 [[BDAutoTrack sharedTrack] startTrack]; //SDK启动 // 在 BDAutoTrack 初始化之后添加方法显示悬浮按钮入口 [BDAutoTrackDevTools showFloatingEntryButton]; return YES; } ``` 3. 查看 SDK 接入版本 / 接入状态

![Image](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/e09585628a1c45798f2d3e0086174aec~tplv-goo7wpa0wc-image.image =250x)

接入栏中显示了 DevTools 对增长营销套件 SDK 的核心信息的检查结果。首次接入增长营销套件 SDK 时可以通过该栏信息判断是否接入成功。

4. 查看事件状态

![Image](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/6e48953d16a04d27aa0c919363ce4027~tplv-goo7wpa0wc-image.image =250x)

在 DevTools 面板中的功能栏点击“事件”即可切换到事件栏。通过实时查看事件信息可以检查事件参数与查看事件状态。

5. 查看网络状态

![Image](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/d4c8ebb962aa456b99f8941b05c50e16~tplv-goo7wpa0wc-image.image =250x)

![Image](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/f7501b9182644b6b9e8d867506f7dcf8~tplv-goo7wpa0wc-image.image =250x)

在控制台面板中点击“网络”即可进入网络抓包页面。通过网络请求的状态和请求体可以查看埋点上报是否成功。

:::tip Devtools详细文档请查阅[iOS埋点开发工具](https://www.volcengine.com/docs/76880/1033613) ::: ## 更多SDK集成实践 ### 初始化相关配置详情请参见[初始化相关配置](/docs/84129/1587779#d79309ce)。 ### 事件及属性、事件公共属性详情请参见[事件及属性、事件公共属性](/docs/84129/1587779#c984e5ef)。 ### 上报自定义用户属性详情请参见[设置用户属性](/docs/84129/1587779#d4d81dd9)。 ### 采集上报元素曝光事件详情请参见[元素曝光功能API说明](/docs/84129/1587781#3a47e9f2)。 ### 设置请求加密详情请参见[加密设置开关](/docs/84129/1587779#db939140)。 ### 更多场景实践更多场景实践请参见[iOS SDK 集成场景实践](/docs/84129/1587779)。 # 埋点数据验证完成初始化验证后，您可以在客户端进行测试操作，触发一些待采集上报的事件，测试事件上报后，大约15分钟内，您可以在`增长分析平台`中的`用户细查`页面查看具体用户行为流数据，即能看到测试事件及事件属性数据，用于验证埋点数据是否可正常采集上报。 * 用户细查页面中展示的用户行为流数据通常有固定的格式，主要包括`user`、`header`、`events`三个部分，分别展示采集上报的用户属性数据、公共事件属性属性、事件及事件属性数据，上报的数据包含了开启采集的预置和自定义的数据。 * 如果在用户细查处能看到对应事件，表明事件上报成功，通过观察事件的属性，可以确认相应属性是否也成功上报上来了。 * 如果数据没有正常在用户细查中查询到，您可检查一下： * 上报数据的数据格式等是否符合要求：[支持的数据格式与事件/属性分类](/docs/84129/1261719)。 * 检查下集成代码中的AppID是否正确：[导入并初始化](/docs/84129/1566348#eaa78476)。 * SaaS-云原生环境和私有化环境的话，需检查下集成代码中的上报域名是否配置正确：[关于各环境上报域名示例](/docs/84129/1587783#aa5148af)。

# iOS SDK API 列表 DataFinder为您提供了丰富的API接口，除了上述通用流程中介绍的核心接口和典型场景的使用示例外，您也可以了解当前iOS 支持的主要API接口和其作用，根据业务需求可灵活调用对应接口完成业务数据埋点。 | | | | \ |分类 |API列表 |API说明 | |---|---|---| | | | | \ |全局API |[sharedTrackWithConfig](/docs/84129/1587781#d7a3a62d) |初始化单例，调用时机：1、必须在应用启动时调用，即在 application:didFinishLaunchingWithOptions: 中调用；2、必须在主线程中调用；3、必须在 SDK 其他方法调用之前调用。 | |^^| | | \ | |[sharedTrack](/docs/84129/1587781#068d02d5) |如果已初始化，则返回之前初始化好的单例；否则返回nil。本身不会做初始化。调用这个方法之前，必须先调用 sharedTrackWithConfig。 | |^^| | | \ | |[startTrack](/docs/84129/1587781#4c0d7a3c) |启动SDK单例，调用时机：1、必须在应用启动时调用，即在 application:didFinishLaunchingWithOptions: 中调用；2、必须在主线程中调用。 | |^^| | | \ | |[trackWithConfig](/docs/84129/1587781#5ad8d06e) |初始化方法，初始化一个实例。初始化接口可以重复调用，会返回一个实例，推荐返回之后，引用住这个实例，下次上报方便使用。 | |^^| | | \ | |[setRequestHostBlock](/docs/84129/1587781#b1ced73c) |设置自定义的Host回调，设置一次即可，不需要多次设置，如果多次设置，会覆盖之前的初始化或者上一次设置的回调，如果为nil会清空回调。 | |^^| | | \ | |[setCurrentUserUniqueID](/docs/84129/1587781#99937276) |设置用户登录态。 | |^^| | | \ | |[clearUserUniqueID](/docs/84129/1587781#627f01f3) |退出用户登录态。 | |^^| | | \ | |[eventV3](/docs/84129/1587781#b2d173ef) |上报事件，在初始化之后设置才能调用。 | |^^| | | \ | |[setCustomHeaderValue](/docs/84129/1587781#c939db2b) |设置自定义的公共属性。 | |^^| | | \ | |[removeCustomHeaderValueForKey](/docs/84129/1587781#237d27fa) |移除自定义的公共属性。 | |^^| | | \ | |[configWithAppID](/docs/84129/1587781#f8805806) |根据App ID获得一个config对象。 | | | | | \ |模块API |[AB实验功能API说明](/docs/84129/1587781#0daa2e24) |SDK提供AB实验能力，并提供了一系列的方法：ABTestConfigValueForKey、ABTestConfigValueSyncForKey:key:defaultValue、abVidsSync、allAbVids、allABTestConfigsSync。 | |^^| | | \ | |[用户属性功能API说明](/docs/84129/1587781#86c82366) |提供设置用户属性能力，并提供了一系列的方法：profileSet、profileSetOnce、profileUnset、profileIncrement、profileAppend。 | |^^| | | \ | |[元素曝光功能API说明](/docs/84129/1587781#3a47e9f2) |本功能在6.10.0+后开始支持。当组件出现在屏幕可视范围内会自动触发一个曝光事件。 | # 参考：数据上报流程与触发时机 ## Event事件上传 ![Image](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/674085a3a2fb40d4a221cd026449bebe~tplv-goo7wpa0wc-image.image =1255x)

* **事件上报触发时机：** * **冷启动**：用户第一次打开APP或者在APP被完全关闭后再次打开时的启动过程。 * **切换前台：**应用程序从后台变为活跃状态，用户可以看到并与之互动。比如，在使用某个APP，然后按下了主页按钮或切换到另一个APP，当你再回到之前的APP时，它就从后台切换到了前台。 * **切换后台：**应用程序从活跃状态变为不活跃状态，虽然它还在运行，但你看不到它在屏幕上。比如，在使用一个APP，然后按下了主页按钮或切换到另一个APP，这个APP就进入了后台。 * **用户Flush 主动触发：**主动调用- (void)flush接口触发上报。SDK有频率限制，每10s最多可以触发一次。 * **设备注册完成：**SDK 内部逻辑，获取事件上报设备标识。 * **采集事件数量超过阈值：**默认200。 * **定时器：**默认60s上传一次。 * **事件上报前置检查**： * device_id & installID 检查（注册接口返回）。 * **数据打包**： * 首次请求Pack最大事件量200条。 * 首次请求成功后将超过200条的后续事件打包走上报流程，单次不超过200条。 * **数据上报**： * 上报成功后删除本地数据库存储、更新本地配置、尝试频控升级。 * 上报失败后重试当前请求，状态码5xx 则进行频控降级处理。 * **请求频控**： * 数据在某段时间内总上报次数受频控限制，超过频控后即使收到新的上报触发也不再处理。 * 请求失败后状态码5xx，会调降当前频控次数。 * 请求成功后对之前调降的频控尝试进行恢复。 ## Profile 用户属性上传 ![Image](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/416b34dd089940d8ade1a5559c6eedb7~tplv-goo7wpa0wc-image.image =1035x)

* **用户属性上报触发时机：** * **冷启动**：用户第一次打开APP或者在APP被完全关闭后再次打开时的启动过程 * **新增Profile：**用户主动调用接口新增Profile设置 * **设备注册完成：**SDK 内部逻辑，获取事件上报设备标识 * 其他流程：与Event上报流程类似，详情可参见上文Event上报流程说明。

增长分析 DataFinder