管理平台

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);

 

 

错误码

描述

解决方法

-3001;

// 初始化失败

检查安全图片

-3002;

// 初始化没有完成

检查安全图片,把初始化提前

-3003;

// 跳转url为null

检查url

3004;

// 打开授权页面失败forJD


-1;

// 获取失败(授权之后,获取过程出错)

程序出错

2; 

// 用户取消授权


1; 

// 授权失败

服务器端失败,重试

176;

//授权登录未确认返回错误码

服务端返回错误码

19;

//Token无效,请退出重试

服务端返回错误码

31;

//短信已经发送,请勿重复提交

服务端返回错误码

20;

//token过期

服务端返回错误码

21;

//token不存在

服务端返回错误码

31;

//短信已经发送,请勿重复提交

服务端返回错误码

257;

//cgi验证图片验证码错误;

服务端返回错误码

258;

//cgi sid,guid过期或不存在错误

服务端返回错误码

259;

//cgi DTC存储错误

服务端返回错误码

260;

//cgi后台服务执行错误

服务端返回错误码

261;

// cgi验证token错误

服务端返回错误码

262;

//cgi验证短信验证码错误

服务端返回错误码

263;

//cgi TPL文件读取错误

服务端返回错误码

264;

//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, 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,原生页面传域名+文章编号。

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

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

 

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

序号

错误码

提示信息

1

0

加入购物车成功

2

30001

sku类型无效

3

30002

未找到sku

4

30003

加入购物车失败

5

30004

绑定用户参数有误

6

30008

加车参数有误

7

30009

查询所有sku失败

8

30010

请求接口参数缺失

9

30012

ip参数格式有误

10

30013

deviceType参数格式有误

11

30014

unionId有误          

 

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

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

KeplerApiManager.getWebViewService().addSkusToCar(BaseStartActivityForSDK.this,
        unionId,
        webId,
        skuIds,
        skuCounts,
        refer, 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)加车接口回调方法,包括加车成功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之后 ,可以设置显示直接返回到第三方应用标签),需邮件提供appkey、返回键名称、bundleId申请,kepler-support@jd.com

 

 

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

mKelperTask=  KeplerApiManager.getWebViewService()

.openItemDetailsPage(sku,

customerInfo,mContext,mOpenAppAction,timeOut);

 

 

呼起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


基础API

可自由调用的数据接口