# 快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/flutter/quickstart
> 介绍 Gravity Engine Flutter SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档为**Flutter**接入 [引力引擎](https://gravity-engine.com/)的技术接入方案，具体 Demo 请参考[GitHub](https://github.com/GravityInfinite/GravityEngine-Flutter-Demo)开源项目，Demo 工程中可以参考 `main.dart` 脚本中对每一个方法的调用示例。
在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview)以了解接入必备的基础概念。
## 1. SDK 基础配置 [#1-sdk-基础配置]
如果要在您的 Flutter 应用中使用GrivityEngine Flutter SDK，请先将 SDK 加入项目。
**请把以下内容添加到你Flutter工程的 pubspec.yaml 文件中：**
> Flutter最新version请参考[gravity-flutter库](https://pub.dev/packages/gravity_engine_flutter_sdk)
```yaml
dependencies:
gravity_engine_flutter_sdk: ^version
```
### 1.1 Android配置 [#11-android配置]
在 `Project` 级别的 `build.gradle` 文件中添加如下配置依赖：
```groovy
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")
```
### 1.2 Harmony配置 [#12-harmony配置]
在App模块启动的Ability里，onCreate方法里添加sdk生命周期
```typescript
import GravityEngineFlutterSdkPlugin from 'gravity_engine_flutter_sdk';
export default class EntryAbility extends FlutterAbility {
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
super.onCreate(want,launchParam);
GravityEngineFlutterSdkPlugin.onFlutterAppStart(this.context,want.parameters);
}
}
```
## 2. 配置并启动 SDK [#2-配置并启动-sdk]
请参考以下代码来进行 SDK 的初始化，建议在能够获取到用户唯一 ID，如Android 设备的`oaid`、iOS 设备的`IDFV`时，尽早的进行初始化。
```dart
import 'package:gravity_engine_flutter_sdk/GravityEngineSDK.dart';
GravityEngineSDK.startGravityEngine(
accessToken:xxxxxxx // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
//预设公共属性
presetSuperProperties:{"testSuperKey":"testSuperValue"}
//鸿蒙应用的clientid在此传入，不传或传空会由引力SDK自动生成
//clientId:xxxxxxx
);
//开启自动采集
GravityEngineSDK.enableAutoTrack([AUTO_TRACK_EVENTS.APP_ALL])
```
## 3. 初始化 [#3-初始化]
### 3.1 添加 att 弹窗描述（iOS配置） [#31-添加-att-弹窗描述ios配置]
需要先在 info.plist 文件中添加跟踪权限请求描述文字，如果不添加会导致 `idfa` 获取失败！描述文字内容仅作示例，具体请联系您的产品同学确认！
```xml
NSUserTrackingUsageDescription
此标识符将用于向您推荐个性化广告。
```
### 3.2 调用引力初始化 [#32-调用引力初始化]
在可以获取到用户唯一性信息时调用本方法，推荐首次安装启动时调用，后续其他方法均需在本方法回调成功之后才可正常使用。
> **Harmony 建议在startGravityEngine之后延迟500ms在调用Harmony 的initialize**
```dart
GravityEngineSDK.initialize(clientId,nickname,enableSyncAttribution,channel,MyCallBack(),adData: {"testAdKey":"testAdValue"});
class MyCallBack extends InitializeCallback {
@override
void onSuccess(Map? 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 | 是 |
| adData | 预设归因信息 | object | 否 |
```dart
GravityEngineSDK.initializeIOS(true,USER_CLIENT_ID,CAID_STR,ENABLE_SYNC_ATTRIBUTION,CHANNEL,MyCallBack(),adData: {"testAdKey":"testAdValue"});
class MyCallBack extends InitializeCallback {
@override
void onSuccess(Map? responseJson) {
// 成功回调的处理
print("Initialization succeeded with response: $responseJson");
}
@override
void onFailed(String? errorMsg) {
// 失败回调的处理
print("Initialization failed with error: $errorMsg");
}
}
```
参数说明：
| **参数名称** | **参数含义** | **参数类型** | **是否必传** |
| ------------------------- | ------------------------------------------------------------------------------------------- | -------- | -------- |
| ENABLE\_ASA | 是否开启 ASA 广告采集，建议传 YES 以开启归因采集能力，由引力后台的归因配置开关控制是否开启ASA归因。 | bool | 是 |
| USER\_CLIENT\_ID | 当前用户在引力系统中的唯一标识，如果传空字符串，则引力 sdk 内部会采集一个稳定的 idfv （保存在 keychain 中保持 idfv 稳定）作为用户唯一标识（推荐传空字符串） | String | 否 |
| CAID\_STR | 当前用户中广协 ID, 类型为json字符串，数组里面是字典，字典里有version和caid字段(可以为空字符串) | String | 是 |
| ENABLE\_SYNC\_ATTRIBUTION | 是否开启同步获取归因信息，具体请参考[同步归因](/docs/attribution/synchronous-attribution) | bool | 是 |
| CHANNEL | 当前用户渠道，您可以自行定义传入的参数，如无自定义的需求，可以传入默认值：appstore | String | 是 |
| adData | 预设归因信息 | object | 否 |
## 4. 事件上报 [#4-事件上报]
### 4.1 业务注册事件上报 [#41-业务注册事件上报]
> **如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。此功能仅适用于需要统计业务注册转化数据的场景。**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `trackRegisterEvent` 方法来上报用户注册事件(`$AppRegister`)给引力，引力会使用该事件统计指标：标准\_注册数
#### 方法示例 [#方法示例]
```dart
static Future trackRegisterEvent();
```
#### 调用示例 [#调用示例]
```dart
GravityEngineSDK.trackRegisterEvent();
```
### 4.2 付费事件上报 [#42-付费事件上报]
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `trackPayEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```dart
static Future trackPayEvent(int payAmount, String payType, String orderId, String payReason, String payMethod);
```
#### 参数说明 [#参数说明]
| **参数名称** | **参数含义** | **参数类型** | **是否必传** |
| --------- | ----------------------------------------------------------------------------------------------------------------- | -------- | -------- |
| payAmount | 付费金额 单位为分。请务必注意，传错单位可能会导致买量受到影响！ | int | 是 |
| payType | 货币类型 按照国际标准组织ISO 4217中规范的3位字母，例如CNY人民币、USD美金等，具体请参考：[国际标准组织 ISO 4217 代码表](https://en.wikipedia.org/wiki/ISO_4217) | String | 是 |
| orderId | 订单号。引力引擎会通过订单号去重，避免重复上报，请务必准确传入！ | String | 是 |
| payReason | 付费原因 例如：购买钻石、办理月卡 | String | 是 |
| payMethod | 付费方式 例如：支付宝、微信、银联等 | String | 是 |
#### 调用示例 [#调用示例-1]
```dart
GravityEngineSDK.trackPayEvent(300, "CNY","order_id","月卡", "支付宝");
```
### 4.3 广告观看事件上报 [#43-广告观看事件上报]
> **广告观看上报适用于广告变现类应用，若您的应用未集成广告模块，则无需接入此事件。**
若您的产品内有广告变现，则需要在用户点击广告观看的同时上报用户广告观看事件给引力，具体参考如下：
#### 方法示例 [#方法示例-2]
```dart
static Future trackAdShowEvent(String adUnionType,String adPlacementId,String adSourceId,String adType,String adnType,double ecpm);
```
#### 参数说明 [#参数说明-1]
为生成准确的广告收益分析报表，请尽量遵循规范填写下方的广告平台参数。正确的字段是生成有价值报表的基础。
我们为您准备了详细的指引： 👉 [广告聚合平台字段配置说明](/docs/appendix/ad-mediation-fields)
| **参数名称** | **参数含义** | **参数类型** | **是否必传** |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------- | -------- |
| adUnionType | 广告聚合平台类型 （取值为：topon、gromore、admore、self，分别对应Topon、Gromore、Admore、自建聚合） | String | 否 |
| adPlacementId | 广告瀑布流ID（广告位ID） | String | 否 |
| adSourceId | 广告源ID（代码位ID） | String | 否 |
| adType | 广告类型 （取值为：reward(激励视频广告)、banner(横幅广告)、 native(信息流广告)、interstitial(插屏广告)、 splash(开屏广告) 、video\_feed(视频信息流)、video\_begin(贴片广告)） | String | 是 |
| adnType | 广告平台类型（取值为：csj、gdt、ks、 mint 、baidu、other，分别对应为穿山甲、优量汇、快手联盟、Mintegral、百度联盟、其他平台） | String | 否 |
| ecpm | 预估ECPM价格（千次展示收入（单位元）） 请务必注意，做好单位转换，传错单位可能会导致买量受到影响！ | Number | 建议填写 |
#### 调用示例 [#调用示例-2]
```dart
GravityEngineSDK.trackAdShowEvent("topon","placement_id","ad_source_id","reward","csj",1.0,);
```
### 4.4 提现事件上报 [#44-提现事件上报]
> **提现事件仅与涉及用户提现功能的平台相关，如无此类业务需求，则无需接入此事件。**
当用户发生应用内提现行为时，需要调用 `trackWithdrawEvent` 方法记录用户提现事件！
#### 方法示例 [#方法示例-3]
```dart
static Future trackWithdrawEvent(int payAmount,String withPayType,String withOrderId,String payReason,String payMethod);
```
#### 参数说明 [#参数说明-2]
| **参数名称** | **参数含义** | **参数类型** | **是否必传** |
| --------- | ------------------------------------------------------------------------------------------------------------- | -------- | -------- |
| payAmount | 提现金额 单位为分 | int | 是 |
| payType | 货币类型 按照国际标准组织ISO 4217中规范的3位字母，例如CNY人民币、USD美金等 [国际标准组织 ISO 4217 代码表](https://en.wikipedia.org/wiki/ISO_4217) | String | 是 |
| orderId | 订单号。引力引擎会通过订单号去重，避免重复上报，请务必传入！ | String | 是 |
| payReason | 提现原因 例如：用户首次提现、用户抽奖提现 | String | 是 |
| payMethod | 提现支付方式 例如：支付宝、微信、银联等 | String | 是 |
#### 调用示例 [#调用示例-3]
```dart
GravityEngineSDK.trackWithdrawEvent(300, "CNY", "order_id_xxxx1", "用户首次提现","支付宝");
```
## 5. 接入验证 [#5-接入验证]
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 5.1 关键事件验证 [#51-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面开启**加载实时数据**，并在产品中触发以下几个事件。事件流使用说明：[事件流 - 飞书云文档](https://gravityengine.feishu.cn/wiki/ZFmYwiDxfiZe2lkt3occ6yBonpf)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | --------------- | ---------- | ---------------------- | --------- | ----------------------- |
| 用户注册 | `$AppRegister` | 用户完成业务注册之后 | 调用SDK的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用SDK的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow` | 用户观看广告之后 | 调用SDK的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 |
| 用户提现 | `$UserWithdraw` | 用户提现之后 | 调用SDK的**上报用户提现事件**方法采集 | 暂无 | 接入了**用户提现上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
如果您之前单独接了媒体的回传(SDK 或者 API)，则上线之前需要去掉，否则可能会导致重复上报数据！
> 至此验证无误之后，您可以正常上线了。