Android SDK 集成

（android studio 集成环境，SDK版本2.2.5及以上版本）

1、客户端SDK接入需要的准备工作

1) 入驻开普勒，创建应用。

2) 下载客户端SDK( 此步骤需要上传您的apk包，通过apk获取到包名，签名等信息，这些信息将生成安全图片)

安全图片：

「安全图片」是开普勒SDK安全机制的一部分，安全图片位于下载的SDK包中，为了是SDK正常工作，需要开发者确保正确的使用安全图片。需要注意以下几点：

· 安全图片的文件名为「safe.jpg」，**请勿修改**。

· 安全图片位于res/raw目录中，通过模块依赖的方式集成SDK，支持移动到第三方应用的res/raw目录。

· 安全图片与开发者编译构建APK所用的keystore对应，如果修改了keystore（比如从debug切换为正式的keystore），则需要替换成对应的安全图片。

2、客户端SDK加入工程

针对不同的IDE有不同的添加方式。本接入文档以Android Studio为例，通过Import Module的方式接入开普勒sdk，如下图。

其中，sdk需要从开普勒官网下载、解压。引入kepler sdk到开发工程后，会在settings.gradle中自动添加include ':KeplerSDK2.2.5'

在apk打包主工程的build.gradle 中添加依赖，即添加dependencies子节点：compile project(':KeplerSDK2.2.5')

3、配置

配置activity

<activity android:name="com.kepler.jd.login.AuthSuccessActivity" 

    android:exported="true" 

    android:screenOrientation="portrait" > 

</activity> 

<activity

            android:name="com.kepler.jd.sdk.KeplerMidActivity"

            android:screenOrientation="portrait"          android:theme="@android:style/Theme.Translucent.NoTitleBar.Fullscreen"       android:windowSoftInputMode="adjustPan|stateHidden"></activity>

<activity android:name="com.kepler.jd.sdk.WebViewActivity" android:screenOrientation="portrait" />

配置权限

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

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

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

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

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

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

配置混淆

-keep class com.kepler.**{*;}

-dontwarn com.kepler.**

4、native功能

1）SDK初始化

使用KeplerApiManager.asyncInitSdk方法来初始化SDK，建议将KeplerApiManager.asyncInitSdk方法的调用放在Application的onCreate中，

在应用启动时就初始化。(SDK中的所有方法都要在主线程中调用)

  （上传APK下载SDK ， 这里需要校验，您的证书(shh)，还有包名（package name），签名与否，请保证这些信息和上传APK一致，否则校验不能通过）

KeplerApiManager.asyncInitSdk(Application.this, appKey, keySecret,

new AsyncInitListener() {

@Override

public void onSuccess() {

Log.e("kepler", "Kepler asyncInitSdk onSuccess ");

}

@Override

public void onFailure() {

Log.e("kepler",

"Kepler asyncInitSdk 授权失败，请检查lib 工程资源引用；包名,签名证书是否和注册一致");

}

});

2）直接授权登录

final LoginListener mLoginListener = new LoginListener() { 

  @Override public void authSuccess() {

//授权登录成功回调方法

      }

@Override public void authFailed(int errorCode) { 

      //授权登录失败回调方法

  }

};

KeplerApiManager.getWebViewService().login(mContext,mLoginListener);

//token不存在

//cgi参数缺失或格式错误，解密失败

**注意**

登录方法登录成功，如果是通过京东APP授权登录，登录态有效时长6个月，如果是M站登录有效时长1个月。

3）验证登录态（验证是否登录）

KeplerApiManager.getWebViewService().checkLoginState(new ActionCallBck() {

                    @Override

                    public boolean onDateCall(int key, String info) {

                        mHandler.post(new Runnable() {

                            @Override

                            public void run() {

                                Toast.makeText(mContext, "已登录", Toast.LENGTH_SHORT).show();

                            }

                        });

                        return false;

                    }

                    @Override

                    public boolean onErrCall(int key, String error) {

                        mHandler.post(new Runnable() {

                            @Override

                            public void run() {

                                Toast.makeText(mContext, "未登录", Toast.LENGTH_SHORT).show();

                            }

                        });

                        return false;

                    }

                });

4）一键添加购物车

在2.2.3版本增加了一键加购功能，接入方调用此方法实现将一个商品添加到购物车。

KeplerApiManager.getWebViewService().addToCart(BaseStartActivityForSDK.this,

                        unionId,

                        webId,

                        skuId,

                        refer,

subUnionId,

new ActionCallBck() {

                            @Override

                            public boolean onDateCall(int key, final String info) {

                                mHandler.post(new Runnable() {

                                    @Override

                                    public void run() {

                                        Toast.makeText(mContext, info, Toast.LENGTH_SHORT).show();

                                    }

                                });

                                return false;

                            }

                            @Override

                            public boolean onErrCall(final int key, final String error) {

                                mHandler.post(new Runnable() {

                                    @Override

                                    public void run() {

                                        Toast.makeText(mContext, "加入购物车失败, code:" +key + "errorMessage:" + error, Toast.LENGTH_SHORT).show();

                                    }

                                });

                                return false;

                            }

                        });

参数说明：

1）unionId：联盟ID，必须传入真实的联盟ID；

2）webId：APPID（查看位置：联盟后台-我的推广-推广管理-APP管理）；

3）skuId：加车商品的skuId；

4）refer：H5文章页面传url，原生页面传域名+文章编号。

5) subUnionId: 此参数是3.0.0版本新增参数。

参数含义：子联盟ID，第三方自定义信息，支持数字，字母，下划线，不支持中文及其他符号（需要向运营人员申请后才可使用）。

参数作用：可用于区分媒体自身的用户ID。

**注意：以上字段需保证真实性，否则会被判为无效订单。**

加车失败，接口返回错误码和错误提示信息如下图。

表1-单个商品加车接口返回错误码和错误提示

5）批量商品一键添加购物车（此处只是接口操作，无页面打开，2.2.5及以上版本支持）

此方法支持一次添加多个商品到购物车，实例代码如下：

KeplerApiManager.getWebViewService().addSkusToCar(BaseStartActivityForSDK.this,
        unionId,
        webId,
        skuIds,
        skuCounts,
        refer,

subUnionId,

new ActionCallBck() {
            @Override
            public boolean onDateCall(int key, final String info) {
                mHandler.post(new Runnable() {
                    @Override
                    public void run() {
                        Toast.makeText(mContext, info, Toast.LENGTH_SHORT).show();
                        checkLoginStatus();
                    }
                });
                return false;
            }

            @Override
            public boolean onErrCall(final int key, final String error) {
                mHandler.post(new Runnable() {
                    @Override
                    public void run() {
                        Toast.makeText(mContext, "加入购物车失败, code:" + key + "errorMessage:" + error, Toast.LENGTH_SHORT).show();
                    }
                });
                return false;
            }
        });

方法及参数说明：

public void addSkusToCar(final Activity activity, final String unionId, final String webId, final String skuIDs, final String skuCounts,final String refer, final ActionCallBck mNetCallBck);

参数说明：

1）unionId：联盟ID，必须传入真实的联盟ID；

2）webId：APPID（查看位置：联盟后台-我的推广-推广管理-APP管理）；

3）skuIds：加车商品的skuId，以逗号分隔；

4）skuCounts：加车商品的数量，以逗号分隔；

5）refer：H5文章页面传url，原生页面传域名+文章编号；

6）subUnionId：此参数是3.0.0版本新增参数。

参数含义：子联盟ID，第三方自定义信息，支持数字，字母，下划线，不支持中文及其他符号（需要向运营人员申请后才可使用）。

参数作用：可用于区分媒体自身的用户ID。

7）加车接口回调方法，包括加车成功onDateCall(int key, final String info)、加车失败onErrCall(final int key, final String error)。其中，加车失败回调方法的key和error可作为排查加车失败原因，可参考单个商品加车失败错误码对照表1。

**注意：以上字段需保证真实性，否则会被判为无效订单。**

5、参数

1、KeplerAttachParameter

从2.2.0版本，该对象作为入口参数，承载以下字段功能：

setCustomerInfo(String kepler_customer_Info)

// 该参数据为第三方应用自定义参数，可以为页面，频道标示，实现统计，打点等需求，在订单维度会存储此字段。

// 传参长度，使用URL encode之后长度必须小于256字节，否则会抛出异常

//严禁传入中文以及以下特殊字符  (=#%&+?< {})

setPositionId(int positionId)

// 该参数据为计费参数

2、KeplerGlobalParameter

//为全局参数设置项，使用单例

KeplerGlobalParameter.getSingleton().setVirtualAppkey(appkey2);

//计费到另外一个账号体系

（注意：必须是多个不同的登录账号下不同app的Appkey

（相同账号体系下，不同的App，使用的是一个分佣体系，所以必须申请多个账号））

setJDappBackTagID(String JDappBackTagID)

//设置打开APP返回的ID(打开jd APP之后 ，可以设置显示直接返回到第三方应用标签)

setActId(String actId)

//设置ActId 内容ID

setExt(String ext)

//设置Ext 内容渠道扩展字段

setGoBackIgnoredUrl(String[] goBackIgnoredUrl)

// 如果使用H5页面，但是第三方传入地址非jd地址，在返回动作，需要跳过的url（防止302导致的无法退出）

6、h5打开页面功能

1）H5功能:打开商品详情SKU

KeplerApiManager.getWebViewService().openItemDetailsWebViewPage("1726755899", mKeplerAttachParameter);

2）H5功能:打开任意页面url

// 也是商品详情 理论上type4 可以打开jd.com 包括pc ,m站 ，手Q，微信手Q，甚至包括金融，钱包等团队的h5页面，但是会有可能出现不可预知的错误，在没有得到我们明确的使用指导下，请详细测试

//不再建议使用以下union url地址，直接使用jd的原生地址也可以完成计费流程

public final static String oneDealUrl = "http://union.click.jd.com/jdc?p=AyIOZRprFQoSAlcZWCVGTV8LRGtMR1dGXgVFSR1JUkpJBUkcU0QLTh" 

+ "9HRwwHXRteFwARGAxeB0gMVQsQDAFBSkVEC0dXZUNTcRFFBEFaakIBR2tOX1RkHUU5XWFuVyIYC00AZFsJXidlDh43VhleHAYSB1UfaxUFF" 

+ "jdlfSYlVHwHVBpaFAMTBFASaxQyEgJRHV4cBBoFVBNfEjIVNwpPHkFSUFMdRR9AUkw3ZRo%3D&t=W1dCFBBFC14NXAAECUteDEYWRQ5RUFc" 

+ "ZVRNbEAAQBEpCHklfHEBZXkxPVlpQFkUHGXJTRiNfBUpWSn8QTwc%3D&e=25840255236224";

KeplerApiManager.getWebViewService().openJDUrlWebViewPage(oneDealUrl ,mKeplerAttachParameter);

4）H5功能:打开导航页面

KeplerApiManager.getWebViewService().openNavigationWebViewPage(mKeplerAttachParameter);

5）H5功能:打开购物车页面

KeplerApiManager.getWebViewService().openCartWebViewPage(mKeplerAttachParameter);

6）H5功能:用户订单页面

KeplerApiManager.getWebViewService().openOrderListWebViewPage(mKeplerAttachParameter);

7）H5功能:取消用户登录

KeplerApiManager.getWebViewService().cancelAuth(Activity.this);

8）H5功能:打开搜索关键词页面

KeplerApiManager.getWebViewService().openSearchWebViewPage("小米", mKeplerAttachParameter);

7、呼起京东 APP 进行相关操作

设置打开APP的事件回调：

OpenAppAction mOpenAppAction = new OpenAppAction() {

@Override

public void onStatus(final int status) {

mHandler.post(new Runnable() {

@Override

public void run() {

if (status == OpenAppAction.OpenAppAction_start) {//开始状态未必一定执行，

dialogShow();

} else {

mKelperTask=null;

dialogDiss();

}

}

});

}

};

打开主APP会产生一个KelperTask

任务可以取消：

mKelperTask.setCancel(true);

timeOut：（打开APP之前，向服务端同步计费信息，这个过程超时，或者出错，H5页面会被打开）

呼起APP 任意URL

mKelperTask= KeplerApiManager.getWebViewService().openJDUrlPage(url, customerInfo,mContext,mOpenAppAction,timeOut);

呼起APP 单品SKU

此方法是唤起京东APP的商品详情页。

mKelperTask=  KeplerApiManager.getWebViewService()

.openItemDetailsPage(sku,

customerInfo,mContext,mOpenAppAction,timeOut);

唤起京喜APP或京东APP单品详情页（3.0.0版本新增）

mKelperTask = KeplerApiManager
        .getWebViewService()
        . openProductDetailPage (skuId,
                customerInfo, this, mOpenAppAction, timeOut);

此方法依据商品类型，按照不同优先级唤起APP。具体如下：

一、如果商品是京喜优选商品或者京东商品，按照1）～3）依次判断：

1） 安装京东APP前提下，唤京东APP。

2） 如果未安装京东APP，安装京喜APP，唤起京喜APP。

3） 如果既未安装京东APP，也未安装京喜APP，则通过WebView方式打开。

二、京喜非优选商品：

安装京喜APP前提下，唤起京喜APP，未安装京喜，WebView方式打开。

如果希望唤起京喜APP展示返回键，需要您配置返回键参数，若不设置，则唤起京喜不展示返回键。

京喜APP配置返回键（3.0.0版本新增）

配置方法可通过KeplerAttachParameter提供的putKeplerAttachParameter方法传递键值对的方式传递。

需要对key为appName，appSchema和appBundleId分别配置key-value键值对。

配置的key保证字母拼写正确、区分大小写、不能有空格等，否则可能出现配置了返回键不生效。

其中，参数含义如下：

appName是返回键名称；

appSchema是返回协议，默认为“sdkback”+用户的appKey组成；

appBundleId 是应用包名。

呼起APP导航页面

mKelperTask= KeplerApiManager.getWebViewService().openNavigationPage(

customerInfo,mContext,mOpenAppAction,timeOut);

呼起APP 打开购物车

mKelperTask=KeplerApiManager.getWebViewService().openCartPage(

customerInfo,mContext,mOpenAppAction,timeOut);

呼起APP 用户订单页面

mKelperTask= KeplerApiManager.getWebViewService().openOrderListPage(

customerInfo,mContext,mOpenAppAction,timeOut);

呼起APP 打开搜索关键词页面

mKelperTask=KeplerApiManager.getWebViewService().openSearchPage(

searchkey, customerInfo,mContext,mOpenAppAction,timeOut);

传递返回 JDappBackTagID

KeplerGlobalParameter.getSingleton().setJDappBackTagID(id);

8、查看开普勒版本号

查看开普勒版本号

KeplerApiManager.getKeplerVersion()

***注意事项***

请不要删除sdk相关cookie，缓存文件，否则可能导致展示、跟单分佣等异常。

详细使用方法请查询demo. URL:Android demo