Android开发手册

# 多端应用开发指南

为降低开发者构建移动应用的开发成本,平台推出基于小程序技术实现的多端框架,基于该多端框架可低成本开发 Android 和 iOS 应用,详情可查看多端框架概述。如果你的 App 是通过官方多端框架开发的,可分别调用如下 JSAPI 即可在 App 中实现微信分享和收藏的功能。

  • 分享图片到微信:wx.miniapp.shareImageMessage
  • 分享小程序卡片到微信:wx.miniapp.shareMiniProgramMessage
  • 分享文本到微信:wx.miniapp.shareTextMessage
  • 分享网页到微信:wx.miniapp.shareWebPageMessage
  • 分享视频到微信:wx.miniapp.shareVideoMessage

# 非多端应用开发指南

如果你的 App 不是通过多端框架开发的,可按照下方的指南在 App 中在集成微信 SDK 后,可调用接口实现微信分享和收藏的功能,以下依次是文字、图片、视频、网页、小程序、音乐视频类型分享的示例。

如果分享的消息中涉及文件路径(如图片类型消息),建议开发者针对 Android 7.0 版本及以上设备,判断微信版本支持的情况下,更新为 FileProvider 的方式进行分享。详情查阅《OpenSDK 支持 FileProvider 方式分享文件到微信文档》

# WXMediaMessage (微信媒体消息内容)说明

字段 类型 含义 备注
sdkVer int sdk 版本号
title String 消息标题 限制长度不超过 512Bytes
description String 消息描述 限制长度不超过 1KB
thumbData byte[] 缩略图的二进制数据 限制内容大小不超过 32KB
mediaObject WXMediaMessage.IMediaObject 消息对象 用于描述一个媒体对象的接口,媒体对象包括:
WXTextObject、WXImageObject、WXVideoObject、WXWebpageObject、 WXFileObject、WXAppExtendObject、WXMiniProgramObject 等
thumbDataHash String 消息缩略图数据的sha256 用于签名,详情可见 OpenSDK 分享签名开发手册
msgSignature String 消息签名 详情可见 OpenSDK 分享签名开发手册

# SendMessageToWX.Req(SendMessageToWX请求类)

分享或收藏的目标场景,通过修改 SendMessageToWX.Req 的scene字段实现。

字段 类型 含义 备注
message WXMediaMessage
scene int 发送的目标场景 分享到对话:
SendMessageToWX.Req.WXSceneSession
分享到朋友圈:
SendMessageToWX.Req.WXSceneTimeline ;
分享到收藏:
SendMessageToWX.Req.WXSceneFavorite
transaction String 对应该请求的事务 ID,通常由 Req 发起,回复 Resp 时应填入对应事务 ID

# 示例

一、文字类型分享示例

WXTextObject (WXMediaMessage.IMediaObject 的派生类,用于描述一个文本对象)

字段 类型 含义 备注
text String 文本数据 长度需大于 0 且不超过 10KB

文字类型分享demo
//初始化一个 WXTextObject 对象,填写分享的文本内容
WXTextObject textObj = new WXTextObject();
textObj.text = text;

//用 WXTextObject 对象初始化一个 WXMediaMessage 对象
WXMediaMessage msg = new WXMediaMessage();
msg.mediaObject = textObj;
msg.description = text;

SendMessageToWX.Req req = new SendMessageToWX.Req();
req.transaction = buildTransaction("text");
req.message = msg;
req.scene = mTargetScene;
//调用api接口,发送数据到微信
api.sendReq(req);


二、图片类型分享示例

WXImageObject (WXMediaMessage.IMediaObject 的派生类,用于描述一个图片对象)

字段 类型 含义 备注
imageData byte[] 图片的二进制数据 内容大小不超过 1MB
imagePath String 图片的本地路径 对应图片内容大小不超过 25MB
imgDataHash String 图片二进制数据的sha256 用于签名,详情可见 OpenSDK 分享签名开发手册

图片类型分享demo
Bitmap bmp = BitmapFactory.decodeResource(getResources(), R.drawable.send_img);

//初始化 WXImageObject 和 WXMediaMessage 对象
WXImageObject imgObj = new WXImageObject(bmp);
WXMediaMessage msg = new WXMediaMessage();
msg.mediaObject = imgObj;

//设置缩略图
Bitmap thumbBmp = Bitmap.createScaledBitmap(bmp, THUMB_SIZE, THUMB_SIZE, true);
bmp.recycle();
msg.thumbData = Util.bmpToByteArray(thumbBmp, true);

//构造一个Req
SendMessageToWX.Req req = new SendMessageToWX.Req();
req.transaction = buildTransaction("img");
req.message = msg;
req.scene = mTargetScene;
req.userOpenId = getOpenId();
//调用api接口,发送数据到微信
api.sendReq(req);

三、视频类型分享示例

WXVideoObject (WXMediaMessage.IMediaObject 的派生类,用于描述一个视频对象)

字段 类型 含义 备注
videoUrl String 视频链接 限制长度不超过 10KB
videoLowBandUrl String 供低带宽的环境下使用的视频链接 限制长度不超过 10KB

注意:videoUrl 和 videoLowBandUrl 不能同时为空

视频类型分享 demo:

//初始化一个WXVideoObject,填写url
WXVideoObject video = new WXVideoObject();
video.videoUrl ="视频url";

//用 WXVideoObject 对象初始化一个 WXMediaMessage 对象
WXMediaMessage msg = new WXMediaMessage(video);
msg.title ="视频标题";
msg.description ="视频描述";
Bitmap thumbBmp = BitmapFactory.decodeResource(getResources(), R.drawable.send_music_thumb);
msg.thumbData =Util.bmpToByteArray(thumbBmp,true);

//构造一个Req
SendMessageToWX.Req req = new SendMessageToWX.Req();
req.transaction = buildTransaction("video");
req.message =msg;
req.scene = mTargetScene;
req.userOpenId = getOpenId();

//调用api接口,发送数据到微信
api.sendReq(req);

四、网页类型分享示例

WXWebpageObject (WXMediaMessage.IMediaObject 的派生类,用于描述一个网页对象)

字段 类型 含义 备注
webpageUrl String html 链接 限制长度不超过 10KB

//初始化一个WXWebpageObject,填写url
WXWebpageObject webpage = new WXWebpageObject();
webpage.webpageUrl ="网页url";

//用 WXWebpageObject 对象初始化一个 WXMediaMessage 对象
WXMediaMessage msg = new WXMediaMessage(webpage);
msg.title ="网页标题 ";
msg.description ="网页描述";
Bitmap thumbBmp = BitmapFactory.decodeResource(getResources(), R.drawable.send_music_thumb);
msg.thumbData =Util.bmpToByteArray(thumbBmp, true);

//构造一个Req
SendMessageToWX.Req req = new SendMessageToWX.Req();
req.transaction = buildTransaction("webpage");
req.message =msg;
req.scene =mTargetScene;
req.userOpenId = getOpenId();

//调用api接口,发送数据到微信
api.sendReq(req);

五、小程序类型分享示例

WXMiniProgramObject (WXMediaMessage.IMediaObject 的派生类,用于描述一个小程序对象)

字段 类型 含义 备注
webpageUrl String 兼容低版本的网页链接 限制长度不超过 10KB
userName String 小程序的原始 id 小程序原始 ID 获取方法:登录小程序管理后台-设置-基本设置-账号信息
path String 小程序的 path 小程序页面路径;对于小游戏,可以只传入 query 部分,来实现传参效果,如:传入 "?foo=bar"
withShareTicket boolean 是否使用带 shareTicket 的分享 通常开发者希望分享出去的小程序被二次打开时可以获取到更多信息,例如群的标识。可以设置 withShareTicket 为 true,当分享卡片在群聊中被其他用户打开时,可以获取到 shareTicket,用于获取更多分享信息。详见小程序获取更多分享信息 ,最低客户端版本要求:6.5.13
miniprogramType int 小程序的类型,默认正式版 正式版: WXMiniProgramObject.MINIPTOGRAM_TYPE_RELEASE;
测试版: WXMiniProgramObject.MINIPROGRAM_TYPE_TEST;
预览版: WXMiniProgramObject.MINIPROGRAM_TYPE_PREVIEW

WXMiniProgramObject miniProgramObj = new WXMiniProgramObject();
miniProgramObj.webpageUrl = "http://www.qq.com"; // 兼容低版本的网页链接
miniProgramObj.miniprogramType = WXMiniProgramObject.MINIPTOGRAM_TYPE_RELEASE;// 正式版:0,测试版:1,体验版:2
miniProgramObj.userName = "gh_d43f693ca31f";     // 小程序原始id
miniProgramObj.path = "/pages/media";            //小程序页面路径;对于小游戏,可以只传入 query 部分,来实现传参效果,如:传入 "?foo=bar"
WXMediaMessage msg = new WXMediaMessage(miniProgramObj);
msg.title = "小程序消息Title";                    // 小程序消息title
msg.description = "小程序消息Desc";               // 小程序消息desc
msg.thumbData = getThumb();                      // 小程序消息封面图片,小于128k

SendMessageToWX.Req req = new SendMessageToWX.Req();
req.transaction = buildTransaction("miniProgram");
req.message = msg;
req.scene = SendMessageToWX.Req.WXSceneSession;  // 目前只支持会话
api.sendReq(req);

六、音乐视频类型分享示例

WXMusicVideoObject(WXMediaMessage.IMediaObject 的派生类,用于描述一个音乐视频对象),Android SDK 6.6.20 及以上版本支持

字段 类型 含义 备注
musicUrl String 音频网页的 URL 地址 必填,不能为空,限制长度不超过 10KB
musicDataUrl String 音频数据的 URL 地址 必填,不能为空,限制长度不超过 10KB
singerName String 歌手名 必填,不能为空,限制长度不超过1KB
duration Int 歌曲时长 必填,单位:毫秒
songLyric String 歌词 建议填写,限制长度不超过32KB
hdAlbumThumbFilePath String 高清专辑图本地文件路径 选填,文件限制长度不超过1MB
albumName String 音乐专辑名 选填
musicGenre String 音乐流派 选填
issueDate Long 发行时间Unix时间戳 选填,单位:秒
identification String 音乐标识符 建议填写,用户在微信音乐播放器跳回应用时会携带该参数,可用于唯一标识一首歌,微信侧不理解
hdAlbumThumbFileHash String 高清专辑封面图sha256 用于签名,详情可见 OpenSDK 分享签名开发手册
WXMusicVideoObject musicVideo = new WXMusicVideoObject();
musicVideo.musicUrl = "https://www.qq.com";	 // 音乐url
musicVideo.musicDataUrl="http://xxx/xx.mp3"; // 音乐音频url
musicVideo.songLyric = "xxx";	// 歌词
musicVideo.hdAlbumThumbFilePath = "xxx";	 // 专辑图本地文件路径
musicVideo.singerName = "xxx";
musicVideo.albumName = "album_xxx";
musicVideo.musicGenre = "流行歌曲";
musicVideo.issueDate = 1610713585;
musicVideo.identification = "sample_identification";
musicVideo.duration = 120000;	// 单位为毫秒

WXMediaMessage msg = new WXMediaMessage();
msg.mediaObject = musicVideo;
msg.title = "歌曲名称";	// 必填,不能为空
msg.description = "歌曲描述";  // 选填,建议与歌手名字段 singerName 保持一致
msg.messageExt = "额外信息";   // 微信跳回应用时会带上
msg.thumbData = getThumb();   // 音乐卡片缩略图,不超过64KB

SendMessageToWX.Req req = new SendMessageToWX.Req();
req.transaction = buildTransaction("musicVideo");
req.message = msg;
req.scene = SendMessageToWX.Req.WXSceneSession;	// 支持会话、朋友圈、收藏
api.sendReq(req);

处理从微信返回到第三方应用,监听com.tencent.mm.opensdk.openapi.IWXAPIEventHandler#onReq回调,处理示例如下:

@Override
public void onReq(BaseReq req) {
	switch (req.getType()) {
		case ConstantsAPI.COMMAND_SHOWMESSAGE_FROM_WX:
			goToShowMsg((ShowMessageFromWX.Req) req);
			break;
		default:
			break;
    }
}

private void goToShowMsg(ShowMessageFromWX.Req showReq) {
		WXMediaMessage wxMsg = showReq.message;
		if (wxMsg.mediaObject instanceof WXMusicVideoObject) {
			WXMusicVideoObject musicVideoObject = (WXMusicVideoObject) wxMsg.mediaObject;
			String identification = musicVideoObject.identification;	// 分享到微信时的音乐标识符字段
			String messageExt = wxMsg.messageExt;	//分享到微信时传的额外信息字段
          	// 应用根据identification与messageExt自行处理
		}
}

音乐视频类型使用说明:

  1. 注意事项:
    • 音乐视频类型与音乐类型不同,分享至微信的音乐视频消息,直接点击好友会话或朋友圈下的分享内容会跳转到微信原生播放器,可以对音乐作品辅以视频制作成音乐视频,进行点赞、评论、发送给朋友、分享到朋友圈、发布至视频号等。
    • 在播放器里点击跳转入口会跳转回App,没有安装App时会打开musicUrl链接。
  2. 音乐视频类型分享,请开发者特别注意必填的字段有:
    • WXMediaMessage.title:歌曲名称
    • WXMusicVideoObject.musicUrl:音频网页的 URL 地址
    • WXMusicVideoObject.musicDataUrl:音频数据的 URL 地址
    • WXMusicVideoObject.singerName:歌手名
    • WXMusicVideoObject.duration:歌曲时长,单位为毫秒
  3. 第三方应用在分享时设置的字段 WXMediaMessage.messageExt 字段与WXMusicVideoObject.identification 需要保证Android与iOS平台是一致的,否则跨平台分享的消息跳转回应用无法保证能够跳转到对应歌曲。
  4. 微信跳转到第三方应用,应用处理 IWXAPIEventHandler.onReq 回调时需要判断WXMediaMessage.mediaObject 的类型进行对应的处理,并且异常情况下也能处理 WXEntryActivity 的关闭,否则可能会导致拉起应用后无法点击操作的问题;无论WXMediaMessage.mediaObject类型是什么,WXMediaMessage.messgeExt 字段均会透传是应用在分享时写入的数据,应用可使用该字段进行应用低版本的兼容处理。

# 注意事项

  1. 发起分享的 App 与小程序属于同一微信开放平台账号。

  2. 或发起分享的 App 与该小程序的代开发(获得小程序权限id为18的授权)服务商的第三方平台账号属于同一微信开放平台账号,也支持发起分享。

  3. 支持分享小程序类型消息至会话,暂不支持分享至朋友圈。

  4. 若客户端版本低于 6.5.6 或在 iPad 客户端接收,小程序类型分享将自动转成网页类型分享。开发者必须填写网页链接字段,确保低版本客户端能正常打开网页链接。

  5. 对于音乐视频类型的分享,需按照如下格式发送邮件至 hansenxu@tencent.com

    • 邮件主题:账号XXX关于音乐视频类 appmsg 的分享功能申请;
    • 邮件内容:需提供移动应用 appid 和需分享的音频网页的域名信息;
    • 要求:
      • 申请账号需为已完成主体认证的账号;
      • 申请“音乐视频类型的分享权限”需先完成“音乐类型的分享权限”申请,且申请的移动应用的 appid 和域名需一致;
      • 音乐视频类型的分享权限会涉及到相关法务协议的签署,具体签订流程和开通结果请参考邮件回复结果。