# 快速集成

> 来源：https://help.gravity-engine.com/docs/client-sdk/web/quickstart
> 介绍 Gravity Engine Web SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。



本文档为 **JavaScript** 接入[引力引擎](https://gravity-engine.com/)的技术接入方案，`JavaScript SDK` 运行环境需为浏览器，暂不兼容 IE 8 及以下版本。

建议您先阅读[接入前准备](/docs/getting-started/overview)以了解接入必备的基础概念。

## 1. SDK 基础配置 [#1-sdk-基础配置]

### 1.1 SDK 引入 [#11-sdk-引入]

下载最新的[SDK](/docs/client-sdk/sdk-overview)文件，并导入到您的项目中，推荐使用 gravityEngine.umd.min.js。

如果您想使用其他类型，使用参考如下：

* 当您想使用 commonjs require 引入时，可使用 gravityEngine.cjs.min.js；
* 当您想使用 es6 import 引入时，可使用 gravityEngine.esm.min.js；

```html
<script src="./gravityengine.umd.min.js"></script>
```

### 1.2 配置并启动 SDK [#12-配置并启动-sdk]

请直接复制以下代码到您项目中需要进行引力引擎初始化的地方，一般建议在能够获取到用户唯一 ID 时调用。

```js
const config = {
  autoTrack: {
    pageShow: true,
    pageHide: true,
  },
  isChina: true, // 是否使用国内域名，默认为 true
  showLog: true,
  useAppTrack: true,
  accessToken: "Yf2HrgFlP6dmNMz5wfytbaorqzJv9i7x", // 项目通行证，在：网站后台 --> 设置 --> 应用列表中找到 Access Token 列 复制（首次使用可能需要先新增应用）
  // clientId: "your_client_id", // 用户唯一标识，如果不传，就用 SDK 生成的 uuid 代替
  // useAppTrack: true, // 设置 Native 打通
};

window.ge = gravityEngine;
ge.setupAndStart(config);
```

## 2. 初始化 [#2-初始化]

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

> 首次调用后，需要在 `initialize` 的 `then` 中**才能继续调用其他事件上报的方法**。
>
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）。

### 方法示例 [#方法示例]

```js
ge.initialize({
  name: "your_name",
  version: 123,
  enable_sync_attribution: false,
  channel: "your_channel",
})
  .then((res) => {
    console.log("initialize success " + res);
  })
  .catch((err) => {
    console.log("initialize failed, error is " + err);
  });
```

### 参数说明 [#参数说明]

| 参数名称                      | 参数含义                                                                | 参数类型    | 是否必传 |
| ------------------------- | ------------------------------------------------------------------- | ------- | ---- |
| name                      | 用户名或用户唯一 ID（可理解为业务中的昵称）                                             | string  | 是    |
| version                   | 用户初始化的程序发布更新的版本号                                                    | number  | 是    |
| enable\_sync\_attribution | 是否开启同步获取归因信息（参考[同步归因](/docs/attribution/synchronous-attribution)文档） | boolean | 是    |
| channel                   | 当前用户来源渠道，对应用户细查中的：客户端渠道（默认值：base\_channel）                          | string  | 否    |

## 3. 事件上报 [#3-事件上报]

### 3.1 付费事件上报 [#31-付费事件上报]

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

> 如果您需要通过后端 API 方式上报付费事件，请参考[混合上报模式](/docs/client-sdk/hybrid-reporting)来接入事件上报接口报送付费事件。

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

#### 方法示例 [#方法示例-1]

```js
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝", true);
```

#### 参数说明 [#参数说明-1]

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

## 4. 接入验证 [#4-接入验证]

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

### 4.1 关键事件验证 [#41-关键事件验证]

在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面开启**加载实时数据**，并在产品中触发以下几个事件。事件流使用说明：[事件流 - 飞书云文档](https://gravityengine.feishu.cn/wiki/ZFmYwiDxfiZe2lkt3occ6yBonpf)

| 事件名 | 事件英文名       | 触发时机   | 采集方式                     | 默认映射到媒体事件 | 备注                      |
| --- | ----------- | ------ | ------------------------ | --------- | ----------------------- |
| 付费  | `$PayEvent` | 用户付费之后 | 调用 SDK 的**上报用户付费事件**方法采集 | 付费        | 接入了**付费事件上报事件**的产品均需要校验 |

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

### 4.2 避免重复上报 [#42-避免重复上报]

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

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