Android JShare集成指南
使用提示
本文是 JSHARE Android SDK 的标准集成指南文档。 匹配的 SDK 版本为:V1.0.0及以后版本。
- 如果你想要快速测试、请参考本文在几分钟内跑通 Demo。
- 极光文档官网上有相关的所有指南、API、教程等全部的文档。包括本文档的更新版本,都会及时地发布到该网站上。
- 极光社区网站:大家对文档有疑惑,以及产品出现问题,可以到极光社区来提问题,可以及时得到回应。
产品功能说明
JSHARE SDK 可以让你的应用支持多平台分享,无需花耗时间了解、集成每个社会化分享平台的 SDK,可以有效的降低包体积。
主要场景:
- 将分享内容分享到 QQ、微信、新浪微博、Facebook、Twitter、趣聊等主要的社交平台。
- 获取QQ、微信、新浪微博、Facebook、Twitter等主要平台的个人信息,用于第三方登录。
Android SDK 版本
JShare SDK支持Android 2.3及以上版本的Android系统。
mavenCentral自动集成
说明 : 使用mavenCentral自动集成的开发者,不需要在项目中添加jar和so,mavenCentral会自动完成依赖。
- 在gradle 配置mavenCentral。
- 配置第三方平台信息。
- 配置微信回调(如不需要分享到微信,可跳过)。
- 配置项目签名。
- 参考example工程或者接口文档使用JShare SDK。
gradle 配置
- 确认android studio的 Project 根目录的主 gradle 中配置了mavenCentral支持。(新建project默认配置就支持)
buildscript {
repositories {
mavenCentral()
}
......
}
allprojects {
repositories {
mavenCentral()
}
}
- 在 module 的 gradle 中添加依赖和AndroidManifest的替换变量。
android {
......
defaultConfig {
applicationId "com.xxx.xxx" //极光控制台创建应用时填写的应用包名.
......
ndk {
//选择要添加的对应cpu类型的.so库。
abiFilters 'armeabi', 'armeabi-v7a', 'armeabi-v8a'
// 还可以添加 'x86', 'x86_64', 'mips', 'mips64'
}
manifestPlaceholders = [
JSHARE_PKGNAME : applicationId,
JPUSH_APPKEY : "你的appkey", //极光控制台创建应用得到的AppKey.
JPUSH_CHANNEL : "developer-default", //暂时填写默认值即可.
TENCENT_APPID: "QQ开发者应用的appID",//腾讯开放平台注册应用得到的appId
FACEBOOK_APPID: "facebook开发者应用的appID",//facebook注册应用得到的appId
]
......
}
......
}
dependencies {
......
compile 'cn.jiguang.sdk:jshare:1.6.0' // 此处以JShare 1.6.0 版本为例,具体版本请参考压缩包libs的jar包版本。
compile 'cn.jiguang.sdk:jshare-qqmodel:1.6.0' // 此处以jshare-qqmodel 1.6.0 版本为例,具体版本请参考压缩包libs的jar包版本。
compile 'cn.jiguang.sdk:jshare-wechatmodel:1.6.0' // 此处以jshare-wechatmodel 1.6.0 版本为例,具体版本请参考压缩包libs的jar包版本。
compile 'cn.jiguang.sdk:jshare-sinamodel:1.6.0' // 此处以jshare-sinamodel 1.6.0 版本为例,具体版本请参考压缩包libs的jar包版本。
compile 'cn.jiguang.sdk:jshare-facebookmodel:1.6.0' // 此处以jshare-facebookmodel 1.6.0 版本为例,具体版本请参考压缩包libs的jar包版本。
compile 'cn.jiguang.sdk:jshare-twittermodel:1.6.0' // 此处以jshare-twittermodel 1.6.0 版本为例,具体版本请参考压缩包libs的jar包版本。
compile 'cn.jiguang.sdk:jshare-jchatpromodel:1.6.0' // 此处以jshare-twittermodel 1.6.0 版本为例,具体版本请参考压缩包libs的jar包版本。
compile 'cn.jiguang.sdk:jbasic:3.1.0' // 此处以 jbasic 3.1.0 版本为例,若同时集成推送/认证,可不需要添加 jbasic 依赖,直接使用 jcore。
......
}
注 : 如果在添加以上 abiFilter 配置之后android Studio出现以下提示:
NDK integration is deprecated in the current plugin. Consider trying the new experimental plugin.
则在 Project 根目录的gradle.properties文件中添加:
android.useDeprecatedNdk=true
组装服务集成步骤
组装服务是对手动集成 SDK 的封装服务,通过将 SDK 组合到单独的 jiguang module ,将手动集成的共同配置业务隐藏,开发者只需关注自己本身的个性化配置,减少集成步骤,提高开发者接入效率。
如您需要使用 JShare 组装服务,请在组装服务界面勾选 JShare 服务,并组装SDK
jiguang_sdk.zip 集成压缩包内容
jiguang
- JIGUANG SDK 组合包
- 资源文件等已在该包中进行依赖,无需在手动拷贝依赖
jiguang-demo
- JIGUANG SDK 组合包集成 demo。
- 是一个完整的 Android 项目,通过这个演示了组包服务的基本用法,可以用来做参考。
- 根据您勾选的服务自动组合构建,组包前预设的相关配置会同时预埋到 demo 中
导入 JIGUANG SDK
通过 AS 将 SDK 作为 module 导入项目
导入步骤:AndroidStudio -> File -> New -> Import Module -> 选择 jiguang 导入
配置 JIGUANG SDK
settings.gradle 配置添加:
include ':jiguang'
在应用 module gradle 中 添加 SDK 依赖
android {
......
defaultConfig {
applicationId "com.xxx.xxx" //JVerification 上注册的包名.
......
manifestPlaceholders = [
JSHARE_PKGNAME : applicationId,
JPUSH_APPKEY : "你的appkey", //极光控制台创建应用得到的AppKey.
JPUSH_CHANNEL : "developer-default", //暂时填写默认值即可.
TENCENT_APPID: "QQ开发者应用的appID",//腾讯开放平台注册应用得到的appId
FACEBOOK_APPID: "facebook开发者应用的appID",//facebook注册应用得到的appId
]
......
}
......
}
dependencies {
......
implementation project(':jiguang')
......
}
手动集成步骤
手动集成压缩包下载链接:前往下载
jshare-android-1.x.y-release.zip 集成压缩包内容
- JGShareSDK.xml
- 客户端嵌入SDK,各个平台配置的参考文件。
- AndroidManifest.xml
- 客户端嵌入SDK参考的配置文件。
- libs/jcore-android-1.x.y.jar
- 极光开发者服务的核.心包。
- jshare-android-1.x.y.jar
- JShare SDK核心包。
- jshare-wechat-android-1.x.y.jar
- JShare微信平台包。
- jshare-qq-android-1.x.y.jar
- JShareQQ平台包。
- jshare-sina-android-1.x.y.jar
- JShare新浪微博包。
- jshare-facebook-android-1.x.y.jar
- JShareFacebook平台包。
- jshare-twitter-android-1.x.y.jar
- JShareTwitter平台包。
- jshare-jchatpro-android-1.x.y.jar
- JShareJChatPro平台包。
- libs/(cpu-type)/libjcore1xy.so
- 各种CPU类型的native开发包。
- example
- 是一个完整的Android项目,通过这个演示了JShare SDK的基本用法,可以用来做参考。
SDK 文件移植
- 解压缩 jshare-android-1.x.y-release.zip 集成压缩包。
- 复制libs/jcore-android-1.x.y.jar到工程libs目录下。
- 复制libs/jshare-android-1.x.y.jar到工程libs目录下。
- 复制libs/(cpu-type)/libjcore1xy.so到你工程中存放对应cpu类型的目录下。
- 根据需要复制libs/jshare-xx.jar平台jar包到工程libs目录下。
- 按下面说明配置AndroidManifest.xml。
- 配置第三方平台信息。
- 配置微信回调(如不需要分享到微信,可跳过)。
- 配置项目签名。
- 参考example工程或者接口文档使用JShare SDK。
说明 : 使用android studio的开发者,如果使用jniLibs文件夹导入so文件,则仅需将所有cpu类型的文件夹拷进去; 如果将so文件添加在module的libs文件夹下,注意在module的gradle配置中添加一下配置:
android {
......
sourceSets {
main {
jniLibs.srcDirs = ['libs']
......
}
......
}
......
}
配置 AndroidManifest.xml
根据 SDK 压缩包里的 AndroidManifest.xml 样例文件,来配置应用程序项目的 AndroidManifest.xml 。
- 复制备注为 "Required" 的部分
- 将标注为“您应用的包名”的部分,替换为当前应用程序的包
- 将标注为“您应用的Appkey”的部分,替换为在Portal上注册该应用的的Key,例如: 9fed5bcb7b9b87413678c407
AndroidManifest 示例
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
android:versionCode="130"
android:versionName="1.3.0"
package="您应用的包名">
<!-- Required -->
<uses-permission android:name="android.permission.RECEIVE_USER_PRESENT" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.VIBRATE" />
<uses-permission android:name="android.permission.MOUNT_UNMOUNT_FILESYSTEMS" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.WRITE_SETTINGS" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<!-- Optional. Required for location feature -->
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_LOCATION_EXTRA_COMMANDS" />
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
<uses-permission android:name="android.permission.GET_TASKS" />
<queries>
<!-- 微信 -->
<package android:name="com.tencent.mm" />
<!-- 微博 -->
<package android:name="com.sina.weibo" />
<!-- QQ -->
<package android:name="com.tencent.mobileqq" />
</queries>
<application
android:name=".MyApplication"
android:allowBackup="true"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:supportsRtl="true"
android:theme="@style/AppTheme">
<activity android:name=".MainActivity">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
<activity android:name=".SelectPlatActivity"/>
<activity android:name=".ShareTypeActivity"/>
<!-- Required SDK核心功能-->
<activity
android:name="cn.jiguang.share.android.ui.JiguangShellActivity"
android:exported="true"
android:launchMode="singleTask"
android:theme="@android:style/Theme.Translucent.NoTitleBar"
android:windowSoftInputMode="stateHidden|adjustResize">
<!-- Optional QQ分享回调-->
<!-- scheme为“tencent”前缀再加上QQ开发者应用的appID;例如appID为123456,则scheme=“tencent123456” -->
<intent-filter>
<data android:scheme="tencent+appID" />
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.BROWSABLE" />
<category android:name="android.intent.category.DEFAULT" />
</intent-filter>
<!-- Optional 新浪微博分享回调 -->
<intent-filter>
<action android:name="com.sina.weibo.sdk.action.ACTION_SDK_REQ_ACTIVITY" />
<category android:name="android.intent.category.DEFAULT" />
</intent-filter>
<!-- Optional 新浪微博私信回调-->
<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="jsharesdk" android:host="sinaweibo"/>
</intent-filter>
</activity>
<!-- Optional 微信分享回调,wxapi必须在包名路径下,否则回调不成功-->
<activity
android:name=".wxapi.WXEntryActivity"
android:theme="@android:style/Theme.Translucent.NoTitleBar"
android:exported="true" />
<!-- Optional facebook配置,authorities必须为com.facebook.app.FacebookContentProvider+APP_ID-->
<provider
android:authorities="com.facebook.app.FacebookContentProvider您申请的facebook的AppId"
android:name="cn.jiguang.share.facebook.FacebookContentProvider"
android:exported="true"
/>
<!-- Optional jchatpro分享回调,plugin必须在包名路径下,否则回调不成功-->
<activity android:name="cn.jiguang.share.demo.plugin.JChatProCallbackActivity"
android:exported="true"
android:theme="@android:style/Theme.Translucent.NoTitleBar"
/>
<!-- User defined. For test only 用户自定义的广播接收器-->
<receiver android:name="cn.jiguang.share.demo.FaceBookUploadReceiver">
<intent-filter>
<action android:name="com.facebook.platform.AppCallResultBroadcast" />
</intent-filter>
</receiver>
<!-- Required. For publish channel feature -->
<!-- JPUSH_CHANNEL 是为了方便开发者统计APK分发渠道。-->
<!-- 例如: -->
<!-- 发到 Google Play 的APK可以设置为 google-play; -->
<!-- 发到其他市场的 APK 可以设置为 xxx-market。 -->
<!-- 目前这个渠道统计功能的报表还未开放。-->
<meta-data
android:name="JPUSH_CHANNEL"
android:value="developer-default" />
<!-- Required. AppKey copied from Portal -->
<meta-data
android:name="JPUSH_APPKEY"
android:value="您应用的Appkey" />
<!--支持Android11以上系统,需要配置分享文件目录访问权限-->
<provider
android:name="android.support.v4.content.FileProvider"
android:authorities="${applicationId}.JSharefileprovider"
android:exported="false"
android:grantUriPermissions="true">
<meta-data
android:name="android.support.FILE_PROVIDER_PATHS"
android:resource="@xml/jshare_file_provider_paths" />
</provider>
</application>
</manifest>
配置分享文件目录访问权限
在Android Studio的res资源目录里,建立子目录xml并新建jshare_file_provider_paths.xml文件,内容为自定义配置分享文件目录访问权限,例如:
<?xml version="1.0" encoding="utf-8"?>
<paths xmlns:android="http://schemas.android.com/apk/res/android">
<!--自定义配置分享文件目录访问权限-->
<external-path name="sample-external-path" path="/"/>
<files-path name="sample-files-path" path="/"/>
</paths>
说明 : jshare_file_provider_paths.xml中各个tag对应的路径,参考自定义配置:
- root-path:表示根目录,"/"。
- files-path:表示 content.getFileDir() 获取到的目录。
- cache-path:表示 content.getCacheDir() 获取到的目录。
- external-path:表示Environment.getExternalStorageDirectory()。
- external-files-path:表示 ContextCompat.getExternalFilesDirs() 获取到的目录。
- external-cache-path:表示 ContextCompat.getExternalCacheDirs() 获取到的目录。
配置第三方平台信息
1.5.0版本开始支持两种方式配置第三方平台信息:1、配置JGShareSDK.xml;2、在代码中设置。开发者应选择其中一种方式,1.5.0之前版本只支持配置JGShareSDK.xml的方式。
JGShareSDK.xml配置第三方平台信息
无论是使用自动集成还是手动集成方式,都需要配置JGShareSDK.xml。 主要步骤为:
- 复制或者新建JGShareSDK.xml到工程目录的asset目录下。
- 把JGShareSDK.xml中相关的AppKey、AppSecret替换成自己在第三方平台创建的应用得到的信息。
- 根据需要配置各个平台,不需要的平台可以删除。
JGShareSDK.xml示例
<?xml version="1.0" encoding="utf-8"?>
<DevInfor>
<!-- 如果不需要支持某平台,可缺省该平台的配置-->
<SinaWeibo
AppKey="新浪微博的AppKey"
AppSecret="新浪微博ppSecret"
RedirectUrl="微博开放平台填写的授权回调页"/>
<QQ
AppId="QQ 的 AppId"
AppKey="QQ 的 AppKey"/>
<Wechat
AppId="微信的 AppId"
AppSecret=" 微信的 AppSectet"/>
<Facebook
AppId="facebook 的 appId"
AppName="facebook 后台填写的名称"
/>
<Twitter
ConsumerKey="twitter 的 ConsumerKey"
ConsumerSecret="twitter 的 ConsumerSecret"
/>
<!-- 趣聊平台appkey的申请, 请查看入门指南的第三方平台申请文档 -->
<JChatPro
auth="申请后的 appkey"
/>
</DevInfor>
代码设置第三方平台信息
详情见SDK初始化API 以及 第三方平台信息设置API;
配置微信平台回调
- 在你的包名相应目录下新建一个wxapi目录,并在该wxapi目录下新增一个WXEntryActivity类,该类继承自WeChatHandleActivity(例如应用程序的包名为cn.jiguang.share.demo,则新添加的类如下图所示)
注意: 如果复写了onCreate方法、onNewIntent方法,那么必须调用父类方法,否者无法获取分享结果,例如:
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
}
@Override
protected void onNewIntent(Intent intent) {
super.onNewIntent(intent);
}
- 并在manifest文件里面加上exported属性,设置为true,例如:
<activity
android:name=".wxapi.WXEntryActivity"
android:theme="@android:style/Theme.Translucent.NoTitleBar"
android:exported="true" />
配置Facebook平台
- 在manifest文件里面添加Facebook的ContentProvider配置:<provider android:authorities="com.facebook.app.FacebookContentProvider您申请的facebook的AppId" android:name="cn.jiguang.share.facebook.FacebookContentProvider" android:exported="true" />
<provider android:authorities="com.facebook.app.FacebookContentProvider您申请的facebook的AppId" android:name="cn.jiguang.share.facebook.FacebookContentProvider" android:exported="true" />
此代码块在浮窗中显示
注意: provider的authorities必须为"com.facebook.app.FacebookContentProvider"+"AppId"。
- 如果需要获取facebook上传图片、视频结果可自定义BroadCastReceiver,继承FacebookBroadcastReceiver,复写onSuccessfulAppCall、onFailedAppCall方法:<receiver android:name="cn.jiguang.share.demo.FaceBookUploadReceiver"> <intent-filter> <action android:name="com.facebook.platform.AppCallResultBroadcast" /> </intent-filter> </receiver>
<receiver android:name="cn.jiguang.share.demo.FaceBookUploadReceiver"> <intent-filter> <action android:name="com.facebook.platform.AppCallResultBroadcast" /> </intent-filter> </receiver>
此代码块在浮窗中显示
注意: receiver的action必须为"com.facebook.platform.AppCallResultBroadcast"。
配置JChatPro平台回调
- 在你的包名相应目录下新建一个plugin目录,并在该plugin目录下新增一个JChatProCallbackActivity类,该类继承自JChatProHandleActivity
注意: 如果复写了onCreate方法、onNewIntent方法,那么必须调用父类方法,否者无法获取分享结果,例如:
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
}
@Override
protected void onNewIntent(Intent intent) {
super.onNewIntent(intent);
}
- 并在manifest文件里面加上exported属性,设置为true,例如:
<activity android:name=".plugin.JChatProCallbackActivity"
android:exported="true"
android:theme="@android:style/Theme.Translucent.NoTitleBar"
/>
配置项目签名
Android Studio图形界面签名配置
进入Project Structure,选择您集成JShare的项目,具体配置如图:
Android Studio手动配置
- 在项目的build.gradle的android内部新增签名配置,例如:
signingConfigs {
debug {
storeFile file("jshare.jks") //签名文件路径
storePassword "sdkteam"
keyAlias "jshare"
keyPassword "sdkteam" //签名密码
}
release {
storeFile file("jshare.jks") //签名文件路径
storePassword "sdkteam"
keyAlias "jshare"
keyPassword "sdkteam" //签名密码
}
}
- 然后在项目的build.gradle的buildTypes使用签名配置,例如:
buildTypes {
release {
minifyEnabled false
proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-project.txt'
signingConfig signingConfigs.debug
}
debug {
signingConfig signingConfigs.debug
}
}
Eclipse环境配置
- 在Eclipse的Preferences,选择Android -> Build,如下图:
- 指定Custom debug keystore选项的路径为sdk demo工程目录中的debug.keystore文件,并应用该配置,如下图:
注意
- 应用的包名、应用的签名、第三方平台注册的AppID及Appkey三者要一一对应,否则会无法分享。
- 应用的签名要与在第三方平台填写的签名对应,否则会无法分享。
- 新浪微博支持未安装客户端分享,需要注意JGShareSDK.xml中的RedirectUrl要与微博开放平台填写的需要一致,否则会发生错误。
添加代码
JShare SDK 提供的 API 接口,都主要集中在 cn.jiguang.share.android.api.JShareInterface 类,使用方法请参考example或者API接口文档。
API基础API
- init 初始化SDK
public static void init(Context context)
- init 初始化SDK,1.5.0后版本支持,在代码中设置第三方平台信息
public static void init(Context context, PlatformConfig platformConfig)
- setDebugMode 设置调试模式
public static void setDebugMode(boolean enable)
注:该接口需在init接口之前调用,避免出现部分日志没打印的情况。多进程情况下建议在自定义的Application中onCreate中调用。
测试确认
- 确认所需要的文件已经添加进工程。
- 确认Androidmanifest.xml已经正确配置。
- 确认第三方平台信息已经正确配置。
- 根据如下日志确定配置了什么平台。
- 确认应用的包名、签名与第三方后台所填写的信息一致。
[PlatformManager] platform Wechat has configured
[PlatformManager] platform SinaWeibo has configured
[PlatformManager] platform QQ has configured
[PlatformManager] platform Facebook has configured
[PlatformManager] platform Twitter has configured
说明: 假如某个平台配置失败,会有log信息,例如:
[PlatformManager] QQ configure fail, please check project config:
make sure jshare-qq-android-v.x.y.jar has build in your project.
混淆配置
-dontwarn cn.jiguang.**
-keep class cn.jiguang.** { *; }
-dontwarn cn.jpush.**
-keep class cn.jpush.** { *; }
-keep public class com.sina.** {
*;
}