本文档为Flutter接入引力引擎的技术接入方案，具体 Demo 请参考GitHub开源项目，Demo 工程中可以参考 main.dart脚本中对每一个方法的调用示例。

在开始接入前，建议您先阅读接入前准备以了解接入必备的基础概念。

1. SDK 基础配置

如果要在您的 Flutter 应用中使用GrivityEngine Flutter SDK，请先将 SDK 加入项目。

请把以下内容添加到你Flutter工程的 pubspec.yaml 文件中：

Flutter最新version请参考gravity-flutter库

dependencies:
  gravity_engine_flutter_sdk: ^version

Android配置

在 Project 级别的 build.gradle 文件中添加如下配置依赖：

maven("https://nexus.gravity-engine.com/repository/maven-releases/")
maven("https://nexus.gravity-engine.com/repository/maven-snapshots/")
maven("https://developer.huawei.com/repo")
maven("https://developer.hihonor.com/repo")

2.配置并启动 SDK

请参考以下代码来进行 SDK 的初始化，建议在能够获取到用户唯一 ID，如Android 设备的oaid、iOS 设备的IDFV时，尽早的进行初始化。

import 'package:gravity_engine_flutter_sdk/GravityEngineSDK.dart';
GravityEngineSDK.startGravityEngine(
      accessToken // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
    );
//开启自动采集
GravityEngineSDK.enableAutoTrack([AUTO_TRACK_EVENTS.APP_ALL])

3.初始化

3.1 添加 att 弹窗描述（iOS配置）

需要先在 info.plist 文件中添加跟踪权限请求描述文字，如果不添加会导致 idfa 获取失败！描述文字内容仅作示例，具体请联系您的产品同学确认！

<key>NSUserTrackingUsageDescription</key>
<string>此标识符将用于向您推荐个性化广告。</string>

3.2 调用引力初始化

在可以获取到用户唯一性信息时调用本方法，推荐首次安装启动时调用，后续其他方法均需在本方法回调成功之后才可正常使用。

Android初始化

GravityEngineSDK.initialize(clientId,nickname,enableSyncAttribution,channel,MyCallBack());
class MyCallBack extends InitializeCallback {
  @override
  void onSuccess(Map<Object?, Object?>? responseJson) {
    // 成功回调的处理
    print("Initialization succeeded with response: $responseJson");
  }

  @override
  void onFailed(String? errorMsg) {
    // 失败回调的处理
    print("Initialization failed with error: $errorMsg");
  }
}

参数说明：

参数名称	参数含义	参数类型	是否必传
clientId	用户唯一 ID(例如 UID 或者设备 ID)。如果传空，则引力 sdk 内部会自动采集设备 id 填入，采集优先级顺序为：oaid > android_id > imei，如果所有id 都采集不到时，会生成随机的 16 位 id 保存到本地缓存中以保持相对稳定	string	是
nickname	用户昵称，如果传空，则引力 sdk 内部会自动根据 client_id 计算 md5 生成	string	否
channel	用户初始化渠道(例如 xiaomi、huawei 等)	string	是
enableSyncAttribution	是否开启同步获取归因信息，具体请参考同步归因	boolean	是

iOS初始化

GravityEngineSDK.initializeIOS(ENABLE_ASA,USER_CLIENT_ID,USER_CAID1_MD5,USER_CAID2_MD5,ENABLE_SYNC_ATTRIBUTION,CHANNEL,MyCallBack());
class MyCallBack extends InitializeCallback {
  @override
  void onSuccess(Map<Object?, Object?>? responseJson) {
    // 成功回调的处理
    print("Initialization succeeded with response: $responseJson");
  }

  @override
  void onFailed(String? errorMsg) {
    // 失败回调的处理
    print("Initialization failed with error: $errorMsg");
  }
}

参数说明：

参数名称	参数含义	参数类型	是否必传
ENABLE_ASA	是否开启 ASA 广告归因，传 YES 则开启，引力会自动获取 ASA 归因信息，传 NO 则引力不会获取。	bool	是
USER_CLIENT_ID	当前用户在引力系统中的唯一标识，如果传空字符串，则引力 sdk 内部会采集一个稳定的 idfv （保存在 keychain 中保持 idfv 稳定）作为用户唯一标识（推荐传空字符串）	String	是
USER_CAID1_MD5	当前用户中广协 ID 的 md5 hash（20230330 版本）（可为空字符串）	String	是
USER_CAID2_MD5	当前用户中广协 ID 的 md5 hash（20250325 版本）（可为空字符串）	String	是
ENABLE_SYNC_ATTRIBUTION	是否开启同步获取归因信息，具体请参考同步归因	bool	是
CHANNEL	当前用户渠道，您可以自行定义传入的参数，如无自定义的需求，可以传入默认值：appstore	String	是

4.事件上报

4.1 业务注册事件上报

如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。此功能仅适用于需要统计业务注册转化数据的场景。

该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）

当用户完成应用内业务注册后，您可以调用 trackRegisterEvent 方法来上报用户注册事件($AppRegister)给引力，引力会使用该事件统计指标：标准_注册数

方法示例

static Future<void> trackRegisterEvent();

调用示例

GravityEngineSDK.trackRegisterEvent();

4.2 付费事件上报

付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。

如果您需要通过后端 API 方式上报付费事件，请参考混合上报模式来接入事件上报接口报送付费事件。

当用户发生付费行为时，需要调用 trackPayEvent 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！

方法示例

 static Future<String?> trackPayEvent( int payAmount,String payType,String orderId,String payReason,String payMethod,);

参数说明

参数名称	参数含义	参数类型	是否必传
payAmount	付费金额单位为分。请务必注意，传错单位可能会导致买量受到影响！	int	是
payType	货币类型按照国际标准组织ISO 4217中规范的3位字母，例如CNY人民币、USD美金等，具体请参考：国际标准组织 ISO 4217 代码表	String	是
orderId	订单号。引力引擎会通过订单号去重，避免重复上报，请务必准确传入！	String	是
payReason	付费原因例如：购买钻石、办理月卡	String	是
payMethod	付费方式例如：支付宝、微信、银联等	String	是

调用示例

 GravityEngineSDK.trackPayEvent(300, "CNY","order_id","月卡", "支付宝");

5.3 广告观看事件上报

广告观看上报适用于广告变现类应用，若您的应用未集成广告模块，则无需接入此事件。

若您的产品内有广告变现，则需要在用户点击广告观看的同时上报用户广告观看事件给引力，具体参考如下：

方法示例

static Future<void> trackAdShowEvent(String adUnionType,String adPlacementId,String adSourceId,String adType,String adnType,double ecpm);

参数说明

为生成准确的广告收益分析报表，请尽量遵循规范填写下方的广告平台参数。正确的字段是生成有价值报表的基础。

我们为您准备了详细的指引： 👉 广告聚合平台字段配置说明

参数名称	参数含义	参数类型	是否必传
adUnionType	广告聚合平台类型（取值为：topon、gromore、admore、self，分别对应Topon、Gromore、Admore、自建聚合）	String	否
adPlacementId	广告瀑布流ID（广告位ID）	String	否
adSourceId	广告源ID（代码位ID）	String	否
adType	广告类型（取值为：reward(激励视频广告)、banner(横幅广告)、 native(信息流广告)、interstitial(插屏广告)、 splash(开屏广告) ）	String	是
adnType	广告平台类型（取值为：csj、gdt、ks、 mint 、baidu、other，分别对应为穿山甲、优量汇、快手联盟、Mintegral、百度联盟、其他平台）	String	否
ecpm	预估ECPM价格（千次展示收入（单位元））请务必注意，做好单位转换，传错单位可能会导致买量受到影响！	Number	建议填写

调用示例

GravityEngineSDK.trackAdShowEvent("topon","placement_id","ad_source_id","reward","csj",1.0,);

5.4 提现事件上报

提现事件仅与涉及用户提现功能的平台相关，如无此类业务需求，则无需接入此事件。

当用户发生应用内提现行为时，需要调用 trackWithdrawEvent 方法记录用户提现事件！

方法示例

static Future<void> trackWithdrawEvent(int payAmount,String withPayType,String withOrderId,String payReason,String payMethod);

参数说明

参数名称	参数含义	参数类型	是否必传
payAmount	提现金额单位为分	int	是
payType	货币类型按照国际标准组织ISO 4217中规范的3位字母，例如CNY人民币、USD美金等国际标准组织 ISO 4217 代码表	String	是
orderId	订单号。引力引擎会通过订单号去重，避免重复上报，请务必传入！	String	是
payReason	提现原因例如：用户首次提现、用户抽奖提现	String	是
payMethod	提现支付方式例如：支付宝、微信、银联等	String	是

调用示例

GravityEngineSDK.trackWithdrawEvent(300, "CNY", "order_id_xxxx1", "用户首次提现","支付宝");

6.接入验证

正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！

6.1 关键事件验证

在引力后台事件流界面开启加载实时数据，并在产品中触发以下几个事件。事件流使用说明：‬⁠⁠‬‌‌‍‍⁠⁠⁠⁠‍⁠‬‍⁠‍‌⁠⁠⁠‬‬事件流 - 飞书云文档

事件名	事件英文名	触发时机	采集方式	默认映射到媒体事件	备注
用户注册	`$AppRegister`	用户完成业务注册之后	调用SDK的上报业务注册事件方法采集	暂无	接入了业务注册上报事件的产品均需要校验
付费	`$PayEvent`	用户付费之后	调用 SDK 的上报用户付费事件方法采集	付费	接入了付费事件上报事件的的产品均需要校验
广告展示	`$AdShow`	用户观看广告之后	调用 SDK 的上报广告展示事件方法采集	暂无	接入了广告事件上报事件的产品均需要校验
用户提现	`$UserWithdraw`	用户提现之后	调用 SDK 的上报用户提现事件方法采集	暂无	接入了用户提现上报事件的产品均需要校验

触发操作后，请在事件流界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。

6.2 避免重复上报

如果您之前单独接了媒体的回传(SDK 或者 API)，则上线之前需要去掉，否则可能会导致重复上报数据！

至此验证无误之后，您可以正常上线了。