优量汇数据上报集成版 iOS SDK 接入文档

概述

集成版SDK同时提供优量汇广告变现能力、用户转化归因和用户行为数据上报能力。本文档旨在帮助应用开发者在程序中快速植入腾讯优量汇开发者平台提供的广告，并对后项的变现与增长数据进行分析。作为应用开发者，您只需要进行简单配置，就可以在您的应用中显示定制的广告，并进行相应的数据上报和分析。

关于 SDK 的具体使用方法，请仔细阅读下面的文档。

前期内测阶段，开发者需申请白名单，才可使用数据上报集成版SDK。白名单申请请联系您的运营经理。

接入指引

开发环境

确保您的开发及部署环境符合以下标准：

• 开发工具：推荐Xcode 11及以上版本

• 部署目标：iOS 9.0及以上版本

• SDK版本：官网最新版本

项目部署

数据上报集成版只支持手动部署，相关步骤请参考手动部署

注册开户

开发者需在腾讯优量汇开发者平台进行注册，在平台审核通过后，开发者就成为了腾讯优量汇的正式会员。

前置条件

接入集成版SDK时，需拔除已接入的转化SDK，否则会报错。

用户转化归因数据接入指引

转化归因功能指的是将广告产生的后续效果（例如：购买，下载，安装等）匹配到具体广告上的过程。是广告主查看报表、投放oCPA广告、优化广告效果所依赖的重要功能。

• 提供创建APP所需要的信息
  提供产品的商品APPID给到运营人员（安卓版本的商品APPID是由运营人员上传包体后返回的）
• 工作人员新建行为数据源
  新建好后，工作人员将返还行为数据源ID和密钥secretKey
• 开发者根据场景部署SDK
  详细流程请参考集成版SDK转化数据接入使用说明文档

提醒

转化SDK上报的商品APPID和变现上报的APPID不相同，请保证ID上报正确性。

注
广告主开发者需要在APP启动时上报APP启动行为，SDK会自主判断这次行为是激活行为、次留行为还是启动行为。

主要API

/* 发送事件
 @param eventName 事件名，不能为nil或者空字符串
 @param params 事件参数，为Dictionary类型，可以为空或者nil。如果param非空，需要可以序列化成jsonString。Param参数总长度不能超过10K。
*/
+ (void)sendEventWithName:(NSString *)eventName extParams:(nullable NSDictionary *)params;

说明：
带有前缀"gt_"的事件为预定义事件，用户自定义事件时不可占用

使用示例

1.首先需要完成转化归因部分的初始化及运行registerAppId注册流量侧的AppId信息，推荐在application: didFinishLaunchingWithOptions:中运行

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
   ......
   // 此处填写您的数据源UserActionSetId和在后台看到的secretKey密钥串
    [GDTAction init:@"YourUserActionSetId" secretKey:@"your secretKey"];
    BOOL result = [GDTSDKConfig registerAppId:@"Your App Id"];
    if (result) {
        NSLog(@"注册成功");
    }
   ......
}

2.应用启动时上报START_APP事件。可以在在applicationDidBecomeActive方法中调用logAction:StartApp上报应用启动行为。

- (void)applicationDidBecomeActive:(UIApplication *)application {

    /*
     * 在应用启动的时候请上报GDTSDKActionNameStartApp行为
     * SDK内部会判断此次启动行为是否为激活行为并上报，开发者无需另外作判断逻辑
     */
    [GDTAction logAction:GDTSDKActionNameStartApp actionParam:@{@"value":@(123)}];
}

-(BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
    /*
     * 在应用被呼起的时候请上报GDTSDKActionNameStartApp行为，并带上呼起的openURL链接
     * 
     */
    [GDTAction logAction:GDTSDKActionNameStartApp actionParam:@{GDTSDKActionParamKeyOpenUrl:url.absoluteString}];
    return true;    
}

3.在发生内购付费时，上报内购事件

#import <GDTAction+convenience.h>
- (void)didPurchase
{
    ......
    // 用户完成内购付费时上报，需要上报金额，请注意设置上报金额的单位，传真实货币类型，ISO 4217代码，如：“USD”
    [GDTAction reportPurchaseActionWithContentType:@"aa" contentName:@"手机" contentID:@"ddd" contentNumber:5 paymentChannel:@"wechat" realCurrency:@"USD" currencyAmount:100 isSuccess:YES];

    ......
}

用户行为数据接入指引

标准化事件

用户行为事件指用户在应用内产生的行为，针对行为事件上报，通过SDK需要上报3个字段：事件标识、字段标识、字段值。

	描述	类型	是否必填	限制	样例
事件名称	事件名称	string	用户在开发者平台新建事件时必填；SDK无需上报	30个字符串以内	事件名A
事件标识	用来标识需要上报的事件，SDK上报时以该标识为准	string	必填	仅支持数字/字母/下划线	your_event_id
字段名称	用于事件上报的附属字段	string	用户在开发者平台新建事件时必填；SDK无需上报	100个字符串以内	事件附属字段名称A
字段标识	用于事件上报的附属字段标识，可通过代码识别对应数据	string	选填	仅支持数字/字母/下划线；每个事件最多可建10个字段标识	max_lev
字段值	用户自定义上报	string	选填	如果字段标识和字段值非空，需要可以序列化成jsonString，且总长度不能超过10KB	100

优量汇提供标准化行为事件供开发者选择上报。标准化事件的事件名称/事件标识和字段名称/字段标识都是固定的，不可修改，开发者参考标准化事件列表上报即可，字段值可自定义上报；

• 标准化行为上报的规范指引，游戏开发者必须上报如下行为。
  数据上报集成版SDK - 标准化上报行为列表
• 也可详见开发者平台 - 数据中心 -事件管理-- 行为事件管理 模块，筛选标准化事件查看标准化行为事件枚举值。
  

自定义事件

开发者可在腾讯优量汇开发者平台自定义事件：数据中心--事件数据--行为事件管理。开发者自定义事件后，可按自定义事件上报数据，并在事件分析报表查看。

点击新建事件，可自定义事件。

主要API

调用DataDetector接口，进行事件上报。

#import "GDTDataDetector.h"

- (void)sendEvent {
    [GDTDataDetector sendEventWithName:@"your event name" extParams:@{@"your param key":@"your param value"}];
}

事件分析报表

开发者上报了标准化事件或自定义事件数据后，即可在腾讯优量汇开发者平台查看相应的事件数据统计。数据中心--事件数据--事件分析报表

事件分析报表

• 上报用户数UV：触发事件上报的用户总量，单个用户触发两次事件时将被计数两次
• 上报次数PV：触发事件上报的总次数