English
Log In
You can then view all documents
AdSpark(增长参谋)/技术接入文档/广告监测服务/归因服务接入-Android
归因服务接入-Android
Last updated 2024-02-21 14:55:54

重要提示:

  1. 归因服务接入后,会关联归因接入兼容数据接入,全部联调成功后,需要有真实归因数据进来才能真正接入成功,需要创建推广活动,用生成的监测链接配置在对应投放平台上
  2. oppo渠道配置监测链接门槛:需连续7天投放消耗在1w以上
  3. 支持渠道:归因服务支持渠道
  4. 归因SDK接入联调时,开发者应按照以下步骤完成接入,上传数据后再进行联调(数据会保存24h),若开发者老版本缺少必要参数上报,使用新版本联调是会有数据干扰,建议多试几次,该过程主要为了前置检查归因的必要参数是否有上报,避免将问题带到线上;

1. 环境准备

  • Gradle编译环境(Android Studio)

2. SDK接入

方式一:自动集成(推荐使用

project级别的build.gradle文件中添加Maven的仓库地址

示例:

复制

在主modulebuild.gradle文件添加SDK依赖

复制

注意: 6.x 版本开始,app级别的build.gradle,需要添加kotlin相关依赖,如已经添加,可忽略implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.3.61"

方式二:手动集成

如果已经远程引入安装SDK,请忽略此步骤。下载 RangersAppLog Android SDK 解压,将 aar、jar 引入项目libs文件夹。在AndroidStudio项目中,打开project级别的build.gradle,添加:

RangersAppLog Android SDK@6.16.3.zipRangersAppLog Android SDK@6.16.3.zip
686.07 KB

在app module的build.gradle并在dependencies中添加:

复制

3. SDK所需的App权限

SDK需要以下权限,建议在SDK初始化之前尽可能申请到对应权限,否则可能会影响归因结果

权限

说明

使用场景和目的

android.permission.READ_PHONE_STATE

读取IMEI等设备信息作为设备标识

设备注册:初始化读取,生成设备唯一标识,计算设备数

android.permission.ACCESS_WIFI_STATE

获取网络状态(wifi)

设备注册和埋点数据采集:采集设备网络(wifi)信息

android.permission.ACCESS_NETWORK_STATE

获取网络状态

设备注册和埋点数据采集:采集设备网络信息

android.permission.INTERNET

发送网络请求

注册、上报埋点、归因、激活等:上报埋点数据到远程服务器

com.asus.msa.SupplementaryDID.ACCESS

读取oaid

设备注册和深度链接:跨APP标识设备

注:Android 6.0及以上版本,需要在运行时动态检查和申请权限。

4. 初始化SDK

初始化RangersAppLog需要尽可能早如有合规场景,请在同意隐私协议后初始化

提示:本SDK默认支持多进程初始化

初始化参数说明

appid

channel

为AdSpark(增长参谋)应用列表中生成的AppID

自定义,一般为应用市场名称


重要提示:

  1. 针对联调管理功能,在初始化SDK的时候必须开启延迟深度链接能力,示例代码:new InitConfig("your_appid", "your_channel").enableDeferredALink(); 详见下方Applog初始化示例和说明;
  2. 初始化Applog:AppLog.init(this, config,TheActivity.this);
    1. 集成SDK后,会在获得用户授权之后进行SDK的初始化并开始采集信息,为确保合规,请确保您采集用户信息前已得到用户的授权
    2. 为补偿延迟对启动事件的数据影响,调用初始化init方法时增加第三个入参为当前Activity对象,如不采用此方式初始化,会对设备ID获取率有影响, 进而影响归因结果
  1. 初始化后必须设置AppLog.setHeaderInfo("csj_attribution",1)否则会直接影响归因结果。
复制

5. 埋点设计和规范

如果在广告投放平台进行投放时只统计激活数,可忽略此步骤。

如果需要此功能,须根据深度事件进行自定义埋点,然后在平台创建推广活动后关联回传事件类型

5.1 系统事件

系统深度事件

事件类型

事件名称(系统预置)

上报时机

激活(系统自带)

$activation

初始化时

留存(系统自带)

app_launch

应用启动时,开发者可以参考5.2自定义深度事件,即可以使用系统采集激活事件(activation)或者其他自定义事件,作为「留存的开始事件」,后续每天留存判断事件默认为系统采集app_launch(应用启动)

激活(系统自带)

zzcm_quickpush_activation

push时

5.2 自定义事件

设计深度事件埋点时,注意要埋点隔离,避免同一个自定义事件名称用来上报多个深度事件类型,否则会有数据GAP问题,建议直接使用AdSpark(参谋)提供的埋点设计,如有自定义埋点需求,尽量对齐格式。

考虑到开发者事件名称可能和参谋归因产出的激活重复导致数据GAP,禁止开发者使用activation,$activation,app_launch,zzcm_quickpush_activation这四个埋点事件名称

自定义深度事件

事件类型

事件名称

上报时机

注册

grown_attribution_event_register










根据业务场景

次留

grown_attribution_event_retention_2d

付费

grown_attribution_event_purchase

下单

grown_attribution_event_order

关键行为

grown_attribution_event_key_behavior

下载

grown_attribution_event_download

授权

grown_attribution_event_authorization

拉活

grown_attribution_event_app_re_active_wake_up

应用内拉起

grown_attribution_event_deelink

广告变现

grown_attribution_event_ad_purchase

表单提交

grown_attribution_event_form_submit

添加购物车

grown_attribution_event_add_to_cart

自定义激活

grown_attribution_event_custom_activition

自定义注册

grown_attribution_event_custom_register

以下是AdSpark(增长参谋)提供的埋点规范代码,可直接复制到应用内使用

复制

6. 埋点上报

用户行为日志采用事件event + 属性params的形式,事件一般对应多个属性,也可以仅有事件没有属性。代码埋点方案一般由数据分析师或产品运营设计。 仅上报事件的代码埋点,示例如下:

复制

上报事件和对应属性的代码埋点,适用于需要携带额外参数上报,例如付费;示例如下:

复制

例如上报付费场景,自定义事件名称为grown_attribution_event_purchase,以下为两种上报方式示例,选择其中一种即可

复制

7. 自查工具使用

温馨提示:

①此工具可用于检测Applog初始化状态Header设置是否正常埋点是否正常上报,以及涉及到端上其他情况,强烈建议利用起来

②直接参考广告监测:用户自查手册 里,埋点验证相关部分使用Charles抓包确认

7.1 Maven仓库引入

在主modulebuild.gradle文件添加SDK依赖,如已添加,请忽略此步骤

复制

7.2 功能说明

接入要求:

  • 已接入Android Applog SDK,支持的最小版本为6.12.0
  • 工程已支持AndroidX
  • Kotlin版本不低于1.3.70
  • Android版本不低于14

7.2.1 面板入口

打开应用后会看到一个悬浮的按钮,按钮下方是本次启动后产生的事件总数和上报完成百分比(已上报到服务端的事件数/累计采集的事件数),点击该按钮后会打开工具面板

  • DevTools面板页面分标题区、内容区两个部分:
    • 标题区:显示子页面标题、显示APP ID(可切换多实例)和关闭面板按钮;
    • 内容区:显示各个功能栏的具体内容。
图片
7.2.1.1 关闭悬浮入口

悬浮按钮默认在App启动后常驻吸边显示,可拖动调整位置。如果需要隐藏悬浮按钮,可以通过以下两种方式关闭:

  1. 一般建议在App的Debug页面(或开发者工具页面)添加一个新的按钮,来控制悬浮按钮的显示和隐藏。开关的值会默认持久化到本地。
复制

DevTools v3.1.0+版本新接口
注意:在Application的初始化中调用该接口不会生效。

  1. 在DevTools设置页面关闭悬浮显示:
图片
7.2.1.2 手动显示面板

在关闭了悬浮按钮后,如果需要打开DevTools面板,可以在任意位置通过调用以下方法显示:

复制

DevTools v3.1.0+版本新接口

7.2.2 接入栏

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

  • 版本检查:初始化AppLog后会显示版本号和是否接入全埋点。
  • 初始化检查:显示了核心的初始化信息,包含APP ID、渠道、启动状态和服务环境。启动状态:已初始化:执行了AppLog.init之后的状态;已启动:SDK开始正常工作后的状态。
  • 服务接口检查:显示核心网络请求是否正常。
  • 埋点上报检查:显示埋点从采集、本地缓存到上报的过程是否正常。

7.2.3 配置栏

在DevTools面板中的导航栏点击“配置”即可切换到配置栏。配置栏中显示了埋点SDK接入成功的各种配置和下发的参数信息:

  • 基本信息:包含设备注册相关的SSID、uuid、bd_did等信息;
  • 初始化配置:包含初始化传入的参数以及实时设置的配置信息;
  • 服务端配置:包含服务端下发的配置信息;
  • 公共参数配置:包含采集的设备信息和自定义公参,并标记敏感参数;

配置 -> 公共参数配置-> 检查header携带csj_attribution情况

其他设备ID(IMEI、OAID)也可一并检测

7.2.4 事件栏

在DevTools面板中的功能栏点击“事件”即可切换到事件栏。通过实时查看事件信息可以检查事件参数等是否正确。事件栏功能包含:

  • 搜索区:事件列表支持按关键字、事件类型、上报状态、录入状态搜索,支持按时间正序、倒序排列,支持清空当前面板的事件列表,支持手动拉取数据管理中的元数据信息;
  • 事件区:事件列表包含事件的产生时间、事件类型、事件状态等基本信息,点击单个事件可以查看事件详细内容(JSON格式),长按单个事件可以复制事件内容到剪切板。事件状态:已采集:表示事件已产生;已落库:表示事件已缓存到本地;已上报:表示事件已通过网络请求上传到服务端。

7.2.5 日志栏

在DevTools面板中的功能栏点击“日志”即可切换到日志栏。通过查看错误日志等可以快速排查接入等问题。日志栏功能包含:

  • 搜索区:支持按关键字、功能模块、日志级别搜索,支持按时间正序、倒序排列,支持清空当前列表的全部日志、支持分享所有日志(含被清空的日志)到第三方应用;
  • 日志区:实时显示增长营销套件SDK产生的所有日志(无需打开日志开关),点击单个日志可以查看日志详情,日志详情支持复制内容到剪切板,支持解析JSON内容并格式化显示JSON。

7.2.6 网络栏

在DevTools面板中的功能栏点击“网络”即可切换到网络栏。通过网络请求的状态和请求体可以查看埋点上报是否成功。网络栏功能包含:

  • 搜索区:支持按URL、接口类型、请求方式搜索,支持按时间正序、倒序排序,支持清空当前列表的网络请求;
  • 网络区:包含请求时间、耗时、状态码、请求方法等基本信息,点击单个网络请求可以查看详细信息。详情的单个信息内容可长按复制到剪切板。网络请求详细信息包含:完整URL请求的Headers请求体(支持JSON格式化查看)响应的Headers响应体(支持JSON格式化查看)

8. 常见问题

更多问题解决和自查请参考广告监测:用户自查手册

Q :归因服务接入联调时数据有效缓存是多久?

A :SDK初始化即可上报launch和terminal事件,需要检查csj_attribution,此事件24小时有效,一般正常初始化SDK几分钟后即可到平台查看接入是否成功

Q :初始化时channel该怎么填?

A: channel为自定义参数,通常定义为上架的应用市场名称,比如huawei、oppo、vivo等

Q :接入归因服务联调报错时显示缺少csj_attribution回传

A :新接入归因服务的应用必须要设置header(csj_attribution=1),且后续发版要一直保留,缺失会影响归因结果,造成不必要的数据GAP,强烈建议在初始化后设置,具体设置方法如下:AppLog.setHeaderInfo("csj_attribution",1);


Contents
Contact us