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{
    if ([Openinstall setUserActivity:userActivity]){
        return YES;
    }
    //其他第三方回调;
    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{
    if  ([Openinstall setLinkURL:url]){
        return YES;
    }
    //其他第三方回调;
    return YES;
}
//iOS9以上,会优先走这个方法
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(nonnull NSDictionary *)options{
    if  ([Openinstall setLinkURL:url]){
        return YES;
    }
    //其他第三方回调;
    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官网获取应用的AppKeyscheme。将下面文档中的OPENINSTALL_APPKEYOPENINSTALL_SCHEME替换。
(scheme的值详细获取位置:openinstall应用控制台->Android集成->Android应用配置)

2.1 AppKey配置

AndroidManifest.xmlapplication标签中添加

    <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. 快速下载

如果只需要快速下载功能,无需其它功能(携带参数安装、渠道统计、一键拉起),完成初始化相关工作即可

2. 一键拉起

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

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

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

  openinstall:registerWakeupHandler(wakeUpCallBack)

3. 携带参数安装高级版功能

在应用需要安装参数时,调用以下 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/api包并上传

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

下面是apk包的上传界面(后台截图):

上传安装包