com.didabu.appsflyer.unity/README.md

Didabu Unity AppsFlyer

# Didabu Appsflyer Unity插件
## 安装
### 安装方式一
打开根目录Packages/manifest.json文件，先添加scopedRegistries：

```json
  "scopedRegistries": [
    {
      "name": "npmjs",
      "url": "https://registry.npmjs.org",
      "scopes": [
        "com.modesttree.zenject",
        "com.mogafa",
        "com.didabu"
      ]
    }
  ]
```
然后再在dependencies中添加

```json
    "appsflyer-unity-plugin": "https://github.com/AppsFlyerSDK/appsflyer-unity-plugin.git#upm",
    "com.didabu.appsflyer.unity": "0.6.1",
```
最终如下图所示：

![alt manifest](Documentation~/Images/manifest.json.png)

### 安装方式二
从Unity编辑器的Edit菜单中选择Project Settings，打开Project Settings窗口，从左侧栏中选择Package Manager，添加一个新的Registry如下图：

![alt ](Documentation~/Images/PackageManagerSetting.png)

其中：
  * Name填写npmjs
  * Url填写https://registry.npmjs.org
  * Scope(s)填写如下内容：com.modesttree.zenject、com.mogafa、com.didabu  

然后从Unity编辑器的Window菜单选择Package Manager打开Package Manager窗口：

![alt PackageManagerMenu](Documentation~/Images/PackageManagerMenu.png)

在Package Manager窗口上，选择左边的"+"，从git添加：

![alt AddFromGit](Documentation~/Images/AddFromGit.png)

在输入框中输入：https://github.com/AppsFlyerSDK/appsflyer-unity-plugin.git#upm

![alt AddFromGit](Documentation~/Images/AppsflyerGit.png)

点击Add按钮，开始安装官方的Appsflyer Unity插件：

![alt AddFromGit](Documentation~/Images/GetAppsflyerGit.png)

安装完成后，在Packages:In Project中能看到此插件：

![alt AddFromGit](Documentation~/Images/AppsFlyerAdded.png)

在Package Manager窗口上，选择Packages为My Registries

![alt MyRegistries](Documentation~/Images/MyRegistries.png)

然后再从didabu分类下选择需要的Didabu Unity Appsflyer版本安装：

![alt DidabuEventUnity](Documentation~/Images/DidabuAppsflyerUnit.png)

## 使用
### 初始化Appsflyer
使用如下的代码初始化Appsflyer，请尽可能早地调用Appsflyer的初始化：
```csharp
//先添加using
using DidabuCloud.Unity.AppsFlyers;
```
AppsFlyer初始化方法有两个重载：
```csharp
public static Task InitAppsFlyer(this Didabu didabu, string devKey, string bundleId = null, 
      Action<Dictionary<string, object>> onConversionDataSuccess = null, 
      Action<string> onConversionDataFail = null, 
      Action<string> onAppOpenAttribution = null, 
      Action<string> onAppOpenAttributionFailure = null,
      Dictionary<string, string> mediaSourceAdCreativeKeyNameMap = null)
```
其中参数含义如下：
  * didabu: Didabu实例
  * devKey: AppsFlyer开发者Key
  * bundleId: 可选参数，App包名(Android)或应用商店Id(iOS)，如果不传SDK将使用包名
  * onConversionDataSuccess: 可选参数，AppsFlyer初始化成功回调，参见：<https://support.appsflyer.com/hc/en-us/articles/4412870736529#onconversiondatasuccess>
  * onConversionDataFail: 可选参数，AppsFlyer初始化失败回调，参见：<https://support.appsflyer.com/hc/en-us/articles/4412870736529#onconversiondatafail>
  * onAppOpenAttribution: 可选参数，深度链接回调，参见：<https://support.appsflyer.com/hc/en-us/articles/4412870736529#onappopenattribution>
  * onAppOpenAttributionFailure: 可选参数，深度链接失败回调， 参见：<https://support.appsflyer.com/hc/en-us/articles/4412870736529#onappopenattributionfailure>
  * mediaSourceAdCreativeKeyNameMap: 可选参数，各广告平台回调数据中包含有广告素材名称，但是获取这个名称的Key，对于大部分广告平台这个Key为"af_ad"，或者可以由营运人员创建广告链接时主动添加一个"af_ad"的key填写成广告素材名称，但是对于有些平台比如Facebook或Google Ads营运人员无法自己主动添加Key，可以通过这个参数指定平台对应获取广告素材名称的Key列表。

另一个较少参数的重载，各参数的意义同上：
```csharp
public static Task InitAppsFlyer(this Didabu didabu, string devKey, string bundleId,
            Dictionary<string, string> mediaSourceAdCreativeKeyNameMap)
```
开始初始化：

```csharp
    //请尽可能早调用Appsflyer初始化
    await Didabu.Application.InitAppsFlyer("YOUR_APPSFLYER_DEV_KEY", "YOUR_PACKAGE_NAME_OR_BUNDLEID");
```
在初始化时设置回调的例子：

```csharp
   await Didabu.Application.InitAppsFlyer("YOUR_APPSFLYER_DEV_KEY", "YOUR_PACKAGE_NAME_OR_BUNDLEID",
       OnConversionDataSuccess, 
       OnConversionDataFail,
       OnAppOpenAttribution,
       OnAppOpenAttributionFailure
   );

   private void OnConversionDataSuccess(Dictionary<string, object> conversionData)
   {
       //在这里处理conversionData
       //在这里可以直接使用Didabu的归因信息了
       //Didabu.Application.Attribution.IsOrganic，是否自然量
       //Didabu.Application.Attribution.MediaSource，广告来源
       //Didabu.Application.Attribution.Campaign，广告活动
       //Didabu.Application.Attribution.Creative，广告素材
   }
   private void OnConversionDataFail(string error)
   {
       //在这里处理错误信息
   }
   private void OnAppOpenAttribution(string message)
   {
       //在这里处理message
   }
   private void OnAppOpenAttributionFailure(string error)
   {
       //在这里处理错误信息
   }
```
>不需要所有的回调都设置，可以只需设置关心的回调。

在初始化时设置广告平台对应的获取广告素材名称的Key列表（如果Key为"af_ad"不需要设置）
```csharp
   await Didabu.Application.InitAppsFlyer("YOUR_APPSFLYER_DEV_KEY", "YOUR_PACKAGE_NAME_OR_BUNDLEID",
       new Dictionary<string, string>{{"media_source_name","creative_key_name"}});
```

### 启用Appsflyer事件上报
启用AppsFlyer事件上报的方法签名如下：
```csharp
        public static void UseAppsFlyerLogEvent(this Didabu didabu,
            List<string> enabledEventNames = null,
            Dictionary<string, string> eventNameMap = null,
            Dictionary<string, string> eventParameterNameMap = null)
```
其中参数含义如下：
  * didabu: Didabu实例，Didabu.Application
  * enabledEventNames: 可选参数，允许上报的事件名称列表，因为Appsflyer最多支持100个事件，可以通过此参数设置需要上报到AppsFlyer的事件，如果为null或空列表，表示所有事件都要上报
  * eventNameMap: 可选参数，事件名称映射表，Didabu可以同时集成多个事件上报平台（比如AppsFlyer和Firebase Analytics），有些事件名称在各平台有特定的意义，比如应用内购买事件，Didabu为ddb_purchase, Firebase Analytics为in_app_purchase，AppsFlyer为af_purchase，当我们上报此事件时不可能为几个平台单独上报，所以可以通过此参数定义事件名称映射规则。如果不传此参数，默认值为将ddb_purchase映射为af_purchase。
  * eventParameterNameMap：可选参数，事件参数名称映射表，原因如上，如果此参数未设置，默认将ddbRevenue映射为af_revenue。

启用AppsFlyer事件上报：
```csharp
    Didabu.Application.UseAppsFlyerLogEvent();
```
启用AppsFlyer事件上报并且指定需要上报的事件名称及事件名称映射：
```csharp
    Didabu.Application.UseAppsFlyerLogEvent(new List<string>{"ddb_purchase_","spin_", "first_open"},
        new Dictionary<string, string>(){{"ddb_purchase_", "af_purchase"},
        new Dictionary<string, string>(){{"ddbRevenue", "af_revenue"}});
```
> 事件名称的命名规则：
>  * 以“_”结尾的，比如“spin_”表示匹配以“spin_”开始的事件和完全匹配“spin”事件，这样“spin”和“spin_2”都会上报
>  * 不以“_”结尾的，比如“first_open”表示全匹配，只有“first_open”才能上报，如果有"first_open_2"就不会上报

### 上报事件
使用如下代码上报事件：
```csharp
Didabu.Application.LogEvent("test_event");
```