开放平台
取消
开放平台
中文
EN
取消
  • 移动应用

    • # iOS 开发手册

    本文介绍如何在 iOS 移动应用中实现微信分享与收藏功能。

    # 1、多端应用开发指南

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

    # 2、非多端应用开发指南

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

    # WXMediaMessage（微信媒体消息内容）说明

    字段 类型 含义 备注
    title NSString 消息标题 限制长度不超过 512Bytes
    description NSString 描述内容 限制长度不超过 1KB
    thumbData NSData 缩略图的二进制数据 限制内容大小不超过 32KB
    mediaObject NSObject 多媒体数据对象 可以为 WXImageObject、WXMusicVideoObject、WXVideoObject、WXWebpageObject 等
    messageExt NSString 额外信息 mediaObject 为 WXMusicVideoObject 时，从微信音乐播放器内跳回，会携带该参数，长度不能超过 2k。（iOS、Android 双平台要一致）
    thumbDataHash NSString 消息缩略图数据的 SHA256 用于签名，详情可见 OpenSDK 分享签名开发手册
    msgSignature NSString 消息签名 详情可见 OpenSDK 分享签名开发手册

    # SendMessageToWXReq（SendMessageToWX 请求类）

    分享或收藏的目标场景，通过修改 SendMessageToWXReq 的 scene 字段实现。

    字段 类型 含义 备注
    text NSString 发送消息的文本内容
    bText BOOL 是否文本消息 发送消息的类型，包括文本消息和多媒体消息两种，两者只能选择其一，不能同时发送文本和多媒体消息
    message WXMediaMessage 发送消息的多媒体内容
    scene int 发送的目标场景 分享到对话：
    WXSceneSession
    分享到朋友圈：
    WXSceneTimeline
    分享到收藏：
    WXSceneFavorite

    # 示例

    一、文字类型分享示例

    SendMessageToWXReq *req = [[SendMessageToWXReq alloc] init];
req.bText = YES;
req.text = @"分享的内容";
req.scene = WXSceneSession;
[WXApi sendReq:req];

    二、图片类型分享示例

    WXImageObject 多媒体消息中包含的图片数据对象

    字段 类型 含义 备注
    imageData NSData 图片的二进制数据 内容大小不超过 10MB
    imgDataHash NSString 图片二进制数据的 SHA256 用于签名，详情可见 OpenSDK 分享签名开发手册
    entranceMiniProgramUsername NSString 启动小程序 username 分享的图片消息是否要带小程序入口，非空则显示，opensdk 2.0.4 支持，最低客户端版本要求：8.0.48
    entranceMiniProgramPath NSString 启动小程路径 分享的图片消息显示的小程序入口可以跳转的小程序路径，opensdk 2.0.4 支持，最低客户端版本要求：8.0.48
    UIImage *image = [UIImage imageNamed:@"res2.png"];
imageData = UIImageJPEGRepresentation(image, 0.7);

WXImageObject *imageObject = [WXImageObject object];
imageObject.imageData = imageData;

WXMediaMessage *message = [WXMediaMessage message];
NSString *filePath = [[NSBundle mainBundle] pathForResource:@"res5"
                                                     ofType:@"jpg"];
message.thumbData = [NSData dataWithContentsOfFile:filePath];
message.mediaObject = imageObject;

SendMessageToWXReq *req = [[SendMessageToWXReq alloc] init];
req.bText = NO;
req.message = message;
req.scene = WXSceneTimeline;
[WXApi sendReq:req];

    三、视频类型分享示例

    WXVideoObject 多媒体消息中包含的视频数据对象

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

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

    WXVideoObject *videoObject = [WXVideoObject object];
videoObject.videoUrl = @"视频 url";
videoObject.videoLowBandUrl = @"低分辨率视频 url";
WXMediaMessage *message = [WXMediaMessage message];
message.title = @"标题";
message.description = @"描述";
[message setThumbImage:[UIImage imageNamed:@"缩略图.jpg"]];
message.mediaObject = videoObject;
SendMessageToWXReq *req = [[SendMessageToWXReq alloc] init];
req.bText = NO;
req.message = message;
req.scene = WXSceneSession;
[WXApi sendReq:req];

    四、网页类型分享示例

    WXWebpageObject 多媒体消息中包含的网页数据对象

    字段 类型 含义 备注
    webpageUrl NSString html 链接 限制长度不超过 10KB
    WXWebpageObject *webpageObject = [WXWebpageObject object];
webpageObject.webpageUrl = @"https://open.weixin.qq.com";
WXMediaMessage *message = [WXMediaMessage message];
message.title = @"标题";
message.description = @"描述";
[message setThumbImage:[UIImage imageNamed:@"缩略图.jpg"]];
message.mediaObject = webpageObject;
SendMessageToWXReq *req = [[SendMessageToWXReq alloc] init];
req.bText = NO;
req.message = message;
req.scene = WXSceneSession;
[WXApi sendReq:req];

    五、小程序类型分享示例

    WXMiniProgramObject 多媒体消息中包含的小程序数据对象

    字段 类型 含义 备注
    webpageUrl NSString 兼容低版本的网页链接 限制长度不超过 10KB
    userName NSString 小程序的 userName 小程序原始 ID 获取方法：登录小程序管理后台-设置-基本设置-账号信息
    path NSString 小程序的页面路径 小程序页面路径；对于小游戏，可以只传入 query 部分，来实现传参效果，如：传入 "?foo=bar"
    hdImageData NSData 小程序新版本的预览图二进制数据，6.5.9 及以上版本微信客户端支持 限制大小不超过 128KB，自定义图片建议长宽比是 5:4
    withShareTicket BOOL 是否使用带 shareTicket 的分享 通常开发者希望分享出去的小程序被二次打开时可以获取到更多信息，例如群的标识。可以设置 withShareTicket 为 true，当分享卡片在群聊中被其他用户打开时，可以获取到 shareTicket，用于获取更多分享信息。详见 小程序获取更多分享信息，最低客户端版本要求：6.5.13
    miniprogramType WXMiniProgramType 小程序的类型，默认正式版，1.8.1 及以上版本开发者工具包支持分享开发版和体验版小程序 正式版：WXMiniProgramTypeRelease
    测试版：WXMiniProgramTypeTest
    体验版：WXMiniProgramTypePreview
    WXMiniProgramObject *object = [WXMiniProgramObject object];
object.webpageUrl = webpageUrl;
object.userName = userName;
object.path = path;
object.hdImageData = hdImageData;
object.withShareTicket = withShareTicket;
object.miniProgramType = programType;
WXMediaMessage *message = [WXMediaMessage message];
message.title = @"小程序标题";
message.description = @"小程序描述";
message.thumbData = nil;  // 兼容旧版本节点的图片，小于 32KB，新版本优先
                          // 使用 WXMiniProgramObject 的 hdImageData 属性
message.mediaObject = object;
SendMessageToWXReq *req = [[SendMessageToWXReq alloc] init];
req.bText = NO;
req.message = message;
req.scene = WXSceneSession;
[WXApi sendReq:req];

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

    该类型需要 OpenSDK 1.8.9 以及以上版本

    WXMusicVideoObject 多媒体消息中包含的音乐视频数据对象

    字段 类型 含义 备注
    musicUrl NSString 音频网页的 URL 地址 必填，限制长度不超过 10KB
    musicDataUrl NSString 音频数据的 URL 地址 必填，限制长度不超过 10KB
    singerName NSString 歌手名 必填，限制长度不超过 1KB
    duration UInt32 音乐时长，歌曲时间 必填，不能为 0，单位：毫秒
    hdAlbumThumbData NSData 高清专辑封面图 选填，大小不超过 1MB
    albumName NSString 音乐专辑名称 选填
    songLyric NSString 歌词信息 LRC 格式 选填，长度不能超过 32K
    musicGenre NSString 音乐流派 选填
    issueDate UInt64 发行时间 Unix 时间戳 选填，单位：秒
    identification NSString 音乐标识符 选填，建议填写，用户在微信音乐播放器内跳回应用时会携带该参数，可用于唯一标识一首歌，微信侧不理解（iOS、Android 双平台要一致）
    hdAlbumThumbFileHash NSString 高清专辑封面图 SHA256 用于签名，详情可见 OpenSDK 分享签名开发手册

    发送 MV 到微信：

    WXMusicVideoObject *mvObject = [WXMusicVideoObject object];
mvObject.musicUrl = @"音乐 url";
mvObject.musicDataUrl = @"音乐数据 url";
mvObject.singerName = @"歌手名";
mvObject.duration = 60 * 1000;                   // 音乐时长，毫秒
mvObject.hdAlbumThumbData = hdAlbumThumbData;     // 高清专辑封面图
mvObject.albumName = @"专辑名";
mvObject.musicGenre = @"音乐流派";
mvObject.issueDate = 1611116532;                  // 发行时间 Unix 时间戳
mvObject.identification = @"test-identification"; // 音乐标识符

WXMediaMessage *message = [WXMediaMessage message];
message.title = @"歌曲名称";                       // 必填，不能为空
message.messageExt = @"额外信息";                  // 微信跳回时会带上

[message setThumbImage:[UIImage imageNamed:@"缩略图.jpg"]];
message.mediaObject = mvObject;
SendMessageToWXReq *req = [[SendMessageToWXReq alloc] init];
req.bText = NO;
req.message = message;
req.scene = WXSceneSession;
[WXApi sendReq:req];

    处理从微信音乐播放器内跳回：

    #pragma mark - WXApiDelegate

- (void)onReq:(BaseReq *)req {
    if ([req isKindOfClass:[LaunchFromWXReq class]]) {
        LaunchFromWXReq *launchReq = (LaunchFromWXReq *)req;
        NSString* messageExt = launchReq.message.messageExt;  // 分享到微信时的透传额外信息字段
        if ([launchReq.message.mediaObject isKindOfClass:WXMusicVideoObject.class]) {
            WXMusicVideoObject *musicVideoObject = (WXMusicVideoObject *)launchReq.message.mediaObject;
            NSString *identification = musicVideoObject.identification; // 分享到微信时的音乐标识符字段
            // 应用可以根据 messageExt 和 identification 处理逻辑
        }
    }
}

    音乐视频类型使用说明：

    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. 无论 WXMediaMessage.mediaObject 类型是什么，WXMediaMessage.messgeExt 字段均会透传是应用在分享时写入的数据，应用可使用该字段进行应用低版本的兼容处理。

    # 注意事项

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

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

    3. 支持直接分享小程序卡片至会话，分享至朋友圈则会打开 单页模式，请开发者做好适配。

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

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

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