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