新手指南-易信开放平台

易信Android平台SDK使用新手指南

本文将介绍SDK的使用。如果你想详细的了解每个API用法，请查阅 API文档或下载阅读易信SDK Sample 源码。

一、准备

1. 下载易信客户端，并注册一个易信帐号。
2. 使用易信帐号登录开放平台，转到应用管理页面，添加一个新应用。
3. 填写你的应用资料，完成后保存，你会获得一个AppID。
4. 提交审核，只有审核通过的应用才可用于开发。: 审核通过的应用在内容来源处显示你登记时填写的应用名称。否则显示“未审核应用”。

二、下载Android开发工具包

开发工具包主要包含两部分内容：（其中，只有yixin_thridpart_app_sdk_v*.jar是必需的）

yixin_thridpart_app_sdk_v*.jar（每个第三方应用必须要导入该sdk库，用于实现与易信的通信）
yixin_thirdpard_app_sdk_doc_v*.zip（yixin_thridpart_app_sdk_v*.jar 的JavaDoc文档）

下载： Android平台开发工具包

您也可以下载易信第三方APP接入的DEMO程序：点击这里下载范例代码

三、将SDK导入你的项目

1. 在工程中新建一个libs目录，将开发工具包中libs目录下的yixin_thridpart_app_sdk_v*.jar复制到该目录中，如下图所示。: 请将yixin_thridpart_app_sdk_v*.jar以java lib的形式导入到您的android app工程。
2. 右键单击工程属性页Properties，选择Java Build Path中的Libraries这个tab，查看是否已引用yixin_thridpart_app_sdk_v*.jar。如未引用则通过Add JARS...导入yixin_thridpart_app_sdk_v*.jar文件。如下图所示。

四、如何在代码中使用开发工具包

在Android平台上，易信APP和您的APP之间通信分为以下四种场景，您的APP只要相应配置这四种场景的响应代码即可。

说明：APP之间基本的通信接口都是通过接口IYXAPI的单例实现类进行，该单例由工厂YXAPIFactory的静态方法createYXAPI(Context paramContext, String paramAppId)负责创建，参数为context和易信开放平台分配的AppID，这两个参数都不能为空，该创建方法可以重复调用，IYXAPI的实现类只会以单例模式创建一次，并绑定到第三方APP的系统上下文applicationContext上。

同时，需要在您的AndroidManifest.xml文件加上下面2项permission：

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

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

1. 第三方APP启动时向易信注册

任何接入易信的第三方APP，在启动时需要向易信APP注册自己的AppID，即主动把您的Android APP的AppID以广播消息通知给易信APP。考虑到有可能第三方APP会先于易信启动，还需要配置一个易信启动通知的接收者BroadcastReceiver子类，用来接收易信APP的启动通知，并主动进行注册，具体如下：

第三方APP创建一个继承自im.yixin.sdk.api.YXAPIBaseBroadcastReceiver的BroadcastReceiver子类，并实现如下方法：

protected String getAppId()

用来返回第三方APP的AppID。如果第三方APP还需要在易信启动时处理其他相关的业务，可以重载并实现父类的如下回调方法，该方法在父类中默认实现为空：

protected void onAfterYixinStart(final YXMessageProtocol protocol)

完成以上代码的编写之后，需要把该BroadcastReceiver配置到第三方APP的AndroidManifest.xml中，具体如下：

同时，您的Android app启动时，需要调用接口IYXAPI的单例中的注册方法：

boolean registerApp()

向易信进行主动注册，只有在提供非法的AppID或没有安装易信App的情况下，才会返回false，其他情况均返回true。不过您的APP对该返回值可以不作任何处理。

综上，注册通信模块需要第三方Android App：

在AndroidManifest.xml中配置一个自定义的YXAPIBaseBroadcastReceiver子类；
在app启动时调用registerApp()进行注册；

2. 第三方APP发送分享内容到易信

第三方APP通过调用IYXAPI的sendRequest方法发送分享内容到易信：

Boolean sendRequest(BaseReq paramBaseReq);

对于各种类型的内容，如文字，图文，音乐，视频等等，都有对应的BaseReq子类，只要第三方APP按照API文档中的接口数据规范，填上对应的数据进行调用即可。

sendRequest 的实现示例，如下图所示：

3. 接收来自易信的请求和响应

如果你的Android App需要接收易信App发送的请求，或者接收发送到易信App请求的响应结果，需要下面2步操作：

【第一步】在你的Android App的package对应的目录下新建一个yxapi子包（其中package是指您配置在AndroidManifest.xml中的系统package属性），并在该yxapi目录下新增一个必须名为YXEntryActivity类，因为该响应Activity（YXEntryActivity）配置的时候必须name=".yxapi.YXEntryActivity"，同时YXEntryActivity必须继承自BaseYXEntryActivity。

（例如应用程序的包名为im.yixin.sdksample，则新添加的类如下图所示）

并在AndroidManifest.xml文件里面加上exported属性，设置为true。如果您的App是横屏，则YXEntryActivity需要配置转屏属性来支持易信竖屏：android:configChanges="keyboardHidden|orientation|screenSize"。

【第二步】YXEntryActivity必须实现父类BaseYXEntryActivity的3个接口，具体如下：

protected IYXAPI getIYXAPI()

返回根据AppID创建的IYXAPI单例
public void onReq(BaseReq req)；

易信主动发送请求到第三方APP时，易信调用第三方APP的此函数。该函数由父类BaseYXEntryActivity的onCreate或者onNewIntent进行调用。
public void onResp(BaseResp resp)；

易信响应第三方APP的请求时，易信调用第三方APP的此函数。第三方APP通过sendRequest分享内容到易信，易信处理完毕后调用此函数。该函数由父类的onCreate或者onNewIntent进行调用。

【建议】如果第三方APP有一些界面初始化的公共逻辑，可以单独写一个函数，由onReq和onResp负责调用。

4. 内容详情页展现方式

用户在易信会话中点击分享消息时，易信打开由第三方APP提供的内容详情页，以下是各类别详情页的展现方式：

Text 数据无详情页
Image 数据中如果有imageUrl数据，用户点击详情时，跳转到这个URI定义的webview
Music 数据中如果有musicUrl或musicLowBandUrl的数据，用户点击详情时，如果用户在WIFI条件下，优先跳转到musicUrl这个URI定义的webview，在非WIFI条件下，优先跳转到musicLowBandUrl这个URI定义的webview
Video 数据中，用户点击详情时，如果用户在WIFI条件下，优先跳转到videoUrl这个URI定义的webview，在非WIFI条件下，优先跳转到videoLowBandUrl这个URI定义的webview。
WebPage 数据中，用户点击详情时，跳转到webPageUrl定义的webview中

易信打开指定页面的时候，会在原链接后加上参数isappinstalled，标识第三方APP是否安装，即http://xxxx/?isappinstalled=[1|0]，1为已安装，0为未安装。

注意！

1. 如果您更改过Android的签名数据，审核通过后，发现无法进行分享。一般是本机缓存的问题，可以测试查看其他机器中的显示情况，本机删除易信和该应用后重新安装即可解决。

2. 如果需要混淆代码，为了保证sdk的正常使用，需要在proguard.cfg加上下面两行配置：

-keep class im.yixin.sdk.api.YXMessage {*;}
-keep class im.yixin.sdk.api.** implements im.yixin.sdk.api.YXMessage$YXMessageData{*;}

3. 如果您测试用的app签名和发布后的app签名不一致，建议您先用app的测试签名在开放平台进行注册，等测试通过后再修改成APP的发布签名，并提交审核。

4. 处理横屏app打开易信分享的页面转屏问题。其中易信分享对话框所在页面半透明，对横屏app的页面会强制转竖屏，导致背景页面显示错误。具体参考demo的SendToYXActivity#onConfigurationChanged接口实现。