cocos2dx lua 接入指引

从github获取文档和插件

使用openinstall第三方插件文档集成时，如何快速获取AppKey、Associated Domains和scheme，下图为iOS相关配置信息（Android同理）：

一、iOS平台配置

  • 从openinstall官方开源站点github上下载插件
  • 将 iOS 目录下的OpeninstallCocos2dxLua文件夹拷贝到项目的 ios 目录下，然后在Xcode工程左边目录里找到 ios 目录，右键通过 "Add Files to xxx" 添加OpeninstallCocos2dxLua文件夹，add的时候注意勾选“Copy items if needed”、“Create groups”

1. 初始化配置

1.1 配置appKey

根据openinstall官方文档，在Info.plist文件中配置appKey键值对，如下：

    <key>com.openinstall.APP_KEY</key>
    <string>“从openinstall官网后台获取应用的appkey”</string>

1.2 初始化代码

在appAppController.mm文件中引入头文件

#import "Openinstall.h"

在方法application:didFinishLaunchingWithOptions:中引入方法

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [Openinstall init];//尽早调用
    return YES;
}

以下为 一键拉起 功能的相关配置和代码

2. universal links配置（iOS9以后推荐使用）

2.1 相关配置

1）到苹果开发者网站，为当前的 AppID 开启关联域名（Associated Domains）服务：

2）创建新的（或更新现有的）描述文件，下载并导入到Xcode中（通过xcode自动生成的描述文件，可跳过这一步）：

3）在 Xcode 中配置 openinstall 为当前应用生成的关联域名（Associated Domains）（openinstall应用控制台 -> iOS集成 -> iOS应用配置 -> 关联域名（Associated Domains））：

2.2 相关代码

在AppController.mm中引入头文件Openinstall.h，并添加通用链接（Universal Links）回调方法，委托 openinstall 来处理

-(BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray * _Nullable))restorationHandler{
    [Openinstall setUserActivity:userActivity];
    //其他第三方回调；
    return YES;
}

3. scheme配置

3.1 相关配置
在Xcode里选中 Target -> Info -> URL Types，配置 openinstall 为当前应用生成的 Scheme，如图所示：

3.2 scheme相关代码

在AppController.mm中添加scheme回调的方法

//支持目前所有版本的iOS
-(BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation{
    [Openinstall setLinkURL:url];
    //其他第三方回调；
    return YES;
}
//iOS9以上，会优先走这个方法
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(nonnull NSDictionary *)options{
    [Openinstall setLinkURL:url];
    //其他第三方回调；
    return YES;
}

二、Android平台配置

1. 拷贝文件

  • 将 Android 目录下的 src 文件夹下的内容拷贝到项目的 app/src 目录下
  • 将 Android 目录下的 libs/openinstall_vX.X.X.jar 拷贝到项目的 app/libs 目录下

添加应用权限

在AndroidManifest.xml中添加openinstall需要的权限

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

2. 配置AppKey和scheme

从openinstall官网获取应用的AppKey和scheme。将下面文档中的OPENINSTALL_APPKEY和OPENINSTALL_SCHEME替换。
（scheme的值详细获取位置：openinstall应用控制台->Android集成->Android应用配置）

2.1 AppKey配置

在AndroidManifest.xml的application标签中添加

    <meta-data
        android:name="com.openinstall.APP_KEY"
        android:value="OPENINSTALL_APPKEY"/>

2.2 拉起配置

  • 将启动AppActivity继承 openinstall 提供的OpenInstallActivity
  • 给启动AppActivity添加android:launchMode="singleTask"属性
  • 给启动AppActivity添加scheme配置

最终AppActivity的配置大致如下

    <activity
        android:name="org.cocos2dx.lua.AppActivity"
        android:configChanges="orientation|keyboardHidden|screenSize"
        android:label="@string/app_name"
        android:launchMode="singleTask"
        android:screenOrientation="landscape"
        android:theme="@android:style/Theme.NoTitleBar.Fullscreen">

        <intent-filter>
            <action android:name="android.intent.action.MAIN"/>
            <category android:name="android.intent.category.LAUNCHER"/>
        </intent-filter>

        <intent-filter>
            <action android:name="android.intent.action.VIEW"/>

            <category android:name="android.intent.category.DEFAULT"/>
            <category android:name="android.intent.category.BROWSABLE"/>

            <data android:scheme="OPENINSTALL_SCHEME"/>
        </intent-filter>

    </activity>

不采用继承OpenInstallActivity的方式时，可以将OpenInstallActivity中的相关代码拷贝到AppActivity中

三、使用指南

导入openinstall.lua文件到工程里，并在调用方法的时候引用，例如：

  local openinstall = require("app.models.openinstall")
  --require里面是openinstall.lua所在目录

1. 快速安装

如果只需要快速安装功能，无需其它功能（App传参安装、渠道统计、一键拉起），完成初始化相关工作即可

2. 一键拉起

完成文档前面iOS和Android介绍的一键拉起相关配置

获取拉起数据
一般在app启动后的第一个scene去获取

  local function wakeUpCallBack(result)
     print("拉起参数回调:"..result)
  end

  openinstall:registerWakeupHandler(wakeUpCallBack)

3. App传参安装高级版功能

在应用需要安装参数时，调用以下 api 获取由 SDK 保存的安装参数，可重复获取，可设置超时时长，单位秒

  local function getInstallCallBack(result)
     print("安装参数回调:"..result)
  end

  openinstall:getInstall(10, getInstallCallBack)

4. 渠道统计高级版功能

SDK 会自动完成访问量、点击量、安装量、活跃量、留存率等统计工作。其它业务相关统计由开发人员代码埋点上报

4.1 注册上报
根据自身的业务规则，在确保用户完成 app 注册的情况下调用相关api

  openinstall:reportRegister()

4.2 效果点上报
统计终端用户对某些特殊业务的使用效果，如充值金额，分享次数等等。调用接口前，请先进入 openinstall 管理后台 “效果点管理” 中添加效果点，第一个参数对应管理后台效果点ID

  openinstall:reportEffectPoint("effect_test", 1)

四、导出apk/ipa包并上传

  • 代码集成完毕后，需要导出安装包上传openinstall后台，openinstall会自动完成所有的应用配置工作。
  • 上传完成后即可开始在线模拟测试，体验完整的App安装/拉起流程；待测试无误后，再完善下载配置信息。

下面是apk包的上传界面（后台截图）：

上传安装包