iOS 发布收藏我的收藏
收藏
我的收藏背景信息
目前分享分为两种形式的分享:
分享到抖音编辑页
分享到抖音编辑页流程一般为:三方制作好要分享的视频之后,调用 SDK 分享到抖音,会先调起抖音编辑页,最后再到抖音发布页。
分享到抖音发布页
分享到抖音无需经过抖音的编辑页,可以直接到抖音发布页,缩短分享的链路。
前提条件
- •在开始分享之前,请确保您已经完成了 iOS 接入指南中的申请和配置过程。如果您还没有完成,请参考 iOS 接入进行接入。
- •分享功能的实现过程是通过相册来进行跨进程通信,从而实现资源共享。因此,首先要确保您的 App 能够提供相册资源。
- •部分参数和功能仅在最新版本的 SDK 和抖音中可用,请注意具体功能的版本要求。
- •请将需要分享的视频/图片保存到系统相册中。届时传入的分享资源为系统相册的本地标识符(Local Identifier)。需要注意以下几点:
- ◦本地标识符是唯一标识系统相册中每个资源的标识符。它是一个字符串,通常由数字和字母组成。
- ◦在分享视频/图片时,请确保传入正确的本地标识符。如果传入的本地标识符不正确,可能会导致分享失败或分享的资源不正确。
- ◦本地标识符可能会因为系统相册的更新或删除操作而发生变化。因此,如果你在分享之前修改或删除了系统相册中的资源,可能需要重新获取正确的本地标识符。
- ◦如果你遇到了分享失败或分享的资源不正确的问题,请检查传入的本地标识符是否正确,并确保系统相册中的资源没有被修改或删除。
- ◦带品牌 logo 或品牌水印的视频,会命中抖音的审核逻辑,有比较大的 概率导致分享视频推荐降权处理/分享视频下架处理/分享账号被封禁处理。强烈建议第三方应用自行处理好分享内容中的不合规水印。
- ◦分享的话题审核依旧遵循抖音的审核逻辑,强烈建议第三方谨慎拟定话题名称,避免强导流行为。
- •投稿能力(aweme.share)和转发到日常能力(aweme.forward)均需应用申请对应能力的权限。
- ◦登录抖音开放平台控制台,进入目标应用。在应用详情中申请对应能力的权限(Scope)。
- ◦在抖音 30.5.0 以下版本,应用只需申请 aweme.share 权限,即可使用投稿能力和转发到日常能力。
- ◦在抖音 30.5.0 及以上版本,应用需申请 aweme.share 权限以使用投稿能力,申请 aweme.forward 权限以使用转发到日常能力。
操作步骤
第一步:引入头文件
引入 <DouyinOpenSDK/DouyinOpenSDKShare.h> 头文件:
#import <DouyinOpenSDK/DouyinOpenSDKShare.h>
第二步:构造分享的请求
构造分享到抖音的分享请求:
DouyinOpenSDKShareRequest *req = [[DouyinOpenSDKShareRequest alloc] init]; //(可选)设置分享的上下文 // 建议传入OpenAPI中申请的ShareID,分享结果会通过 Webhooks 进行回调。更多信息,请参见查询视频分享结果及数据 req.state = @“placehold_state”;
第三步:设置必传参数
设置分享的资源类型
req.mediaType = DouyinOpenSDKShareMediaTypeImage; // 分享的资源为纯图片类型 // or req.mediaType = DouyinOpenSDKShareMediaTypeVideo; // 分享的资源为纯视频类型
设置分享的资源
req.localIdentifiers = identifiers; // NSArray<NSString *> * (系统相册的本地标识符)
设置分享的目标页面:
req.landedPageType = DouyinOpenSDKLandedPageEdit; // 编辑页面 // or req.landedPageType = DouyinOpenSDKLandedPagePublish; // 发布页面(需要抖音14.7版本以上)
设置是否转发到日常
req.publishStory = NO; // 是否转发到日常,设置为YES的时使用转发到日常能力,设置为NO时使用投稿能力
注意
投稿能力(aweme.share)和转发到日常能力(aweme.forward)均需应用申请对应能力的权限。
在抖音 30.5.0 以下版本,应用只需申请 aweme.share 权限,即可使用投稿能力和转发到日常能力。
在抖音 30.5.0 及以上版本,应用需申请 aweme.share 权限以使用投稿能力,申请 aweme.forward 权限以使用转发到日常能力。
第四步:发送请求
在设置好分享需要带入的信息之后,通过
-[DouyinOpenSDKShareRequest sendShareRequestWithCompleteBlock:]
发送分享请求,结果将通过 CompleteBlock 进行回调。注意:只有抖音主动跳回 App 的时候,才会触发 CompleteBlock 回调。当发布成功后,当用户选择【留在抖音】时,不会触发此回调。
[req sendShareRequestWithCompleteBlock:^(DouyinOpenSDKShareResponse * _Nonnull respond) { NSString *alertString = nil; if (respond.isSucceed) { // Share Succeed } else{ // Share failed } }];
如果分享失败可通过 respond.errCode 获取错误码对应枚举值 BDOpenPlatformErrorCode ,通过 respond.errString 会返回报错信息。
错误码对应表:
BDOpenPlatformErrorCode | errorCode | 描述 |
BDOpenPlatformSuccess | 0 | 成功 |
BDOpenPlatformErrorCodeCommon | -1 | 通用错误类型<包括网络错误> |
BDOpenPlatformErrorCodeUserCanceled | -2 | 用户手动取消 |
BDOpenPlatformErrorCodeSendFailed | -3 | 发送失败 |
BDOpenPlatformErrorCodeAuthDenied | -4 | 权限错误 |
BDOpenPlatformErrorCodeUnsupported | -5 | 不支持 |
如果错误码不能方便你定位具体出错的问题,你可以通过 respond.shareState 进行错误定位。需要接入 SDK 2.0.8 以上版本。
以下为 Share State 信息的对应关系:
BDOpenPlatformShareRespState | value | 描述 |
BDOpenPlatformShareRespStateSuccess | 20000 | 分享成功 |
BDOpenPlatformShareRespStateUnknownError | 20001 | 未知或者当前 SDK 版本未分类错误 |
BDOpenPlatformShareRespStateParamValidError | 20002 | 参数解析错误,获取到的资源和传入的资源类型不一致 |
BDOpenPlatformShareRespStateSharePermissionDenied | 20003 | |
BDOpenPlatformShareRespStateUserNotLogin | 20004 | 用户未登录 |
BDOpenPlatformShareRespStateNotHavePhotoLibraryPermission | 20005 | 抖音没有相册权限 |
BDOpenPlatformShareRespStateNetworkError | 20006 | 抖音网络错误 |
BDOpenPlatformShareRespStateVideoTimeLimitError | 20007 | 视频时长不符合限制 |
BDOpenPlatformShareRespStatePhotoResolutionError | 20008 | 图片资源分辨率不符合限制 |
BDOpenPlatformShareRespTimeStampError | 20009 | 时间戳检查失败 |
BDOpenPlatformShareRespStateHandleMediaError | 20010 | 处理照片资源出错 |
BDOpenPlatformShareRespStateVideoResolutionError | 20011 | 视频分辨率不符合限制 |
BDOpenPlatformShareRespStateVideoFormatError | 20012 | 视频格式不支持 |
BDOpenPlatformShareRespStateCancel | 20013 | 用户取消分享 |
BDOpenPlatformShareRespStateHaveUploadingTask | 20014 | 用户有未完成编辑的发布内容 |
BDOpenPlatformShareRespStateSaveAsDraft | 20015 | 用户将分享内容存储为了草稿或用户账号不允许发布视频 |
BDOpenPlatformShareRespStatePublishFailed | 20016 | 发布视频失败 |
BDOpenPlatformShareRespStateMediaInIcloudError | 21001 | 从 iCloud 同步资源出错 |
BDOpenPlatformShareRespStateParamsParsingError | 21002 | 传递的参数处理错误 |
BDOpenPlatformShareRespStateGetMediaError | 21003 | 获取资源错误资源可能不存在 |
分享内容携带额外信息
设置分享内容的标题
目前支持设置标题,同时标题中支持插入话题和@用户。指定的话题会展现在发布页面,用户可自行删除该话题,该话题类型支持商业化话题和普通话题。发布后同抖音原生话题没有差别。
// 添加标题 req.title = [DouyinOpenSDKShareTitle new]; req.title.text = @"title"; // 正文 req.title.shortTitle = @"shortTitle"; // 标题,只支持 // 添加Hashtag. DouyinOpenSDKTitleHashtag *hashtag = [DouyinOpenSDKTitleHashtag new]; hashtag.text = @"hashtag"; hashtag.index = 0; [req.title.hashtags addObject:hashtag]; // 添加@用户 DouyinOpenSDKTitleMention *mention = [DouyinOpenSDKTitleMention new]; mention.openID = @"openID"; mention.index = 0; [req.title.mentions addObject:hashtag];
注意
- 1.该能力从抖音 21.3.0 版本开始支持。
- 2.标题总长度不超过 500。
- 3.该能力只支持投稿能力。
设置分享内容的贴纸
支持第三方传入贴纸。贴纸会出现在编辑页面,用户可自行移动、删除贴纸。
目前支持话题贴纸、@用户贴纸、图片贴纸、poi 贴纸等。
// 添加图片贴纸 DouyinOpenSDKShareImageSticker *imageSticker = [[DouyinOpenSDKShareImageSticker alloc] init]; imageSticker.localIdentifier = identifier; imageSticker.locationX = @0.5; //proportional position imageSticker.locationY = @0.5; //proportional position imageSticker.maxEdge = @300; // width imageSticker.minimumScale = @0.01; // 用户可手动缩小的最小倍数 imageSticker.deleteable = YES; // 请使用4.1.8及以上版本的SDK imageSticker.editable = YES; // 请使用4.1.8及以上版本的SDK [req.imageStickers addObject:imageSticker]; // 添加话题贴纸 DouyinOpenSDKShareHashtagSticker *hashtagSticker = [[DouyinOpenSDKShareHashtagSticker alloc] init]; hashtagSticker.text = @"hashtag"; hashtagSticker.locationX = @0.5; //proportional position hashtagSticker.locationY = @0.5; //proportional position [req.hashtagStickers addObject:hashtagSticker]; // 添加@用户贴纸 DouyinOpenSDKShareMentionSticker *mentionSticker = [[DouyinOpenSDKShareMentionSticker alloc] init]; mentionSticker.openID = @"mentionSticker"; mentionSticker.locationX = @0.5; //proportional position mentionSticker.locationY = @0.5; //proportional position [req.mentionStickers addObject:mentionSticker]; // 添加POI贴纸 DouyinOpenSDKSharePoiSticker *poiSticker = [[DouyinOpenSDKSharePoiSticker alloc] init]; poiSticker.poiID = @"poiID"; poiSticker.locationX = @0.5; //proportional position poiSticker.locationY = @0.5; //proportional position req.poiStickers = poiSticker;
注意
该能力从抖音 21.3.0 版本开始支持。
设置小程序锚点
支持第三方分享内容至抖音时,携带相关小程序信息,成功发布视频后,在视频左下角带有小程序入口。
// 设置分享携带小程序(小程序与应用必须为同一主体) NSMutableDictionary *m_dic = @{}.mutableCopy; m_dic[@"identifier"] = self.microAppId?:@""; m_dic[@"title"] = self.microAppTitle?:@""; m_dic[@"desc"] = self.microAppDesc?:@""; m_dic[@"startPageURL"] = self.microAppUrl?:@""; // 小程序,在分享的视频右下角显示抖音小程序入口, 非必须属性 req.extraInfo = @{ @"mpInfo" : m_dic.copy, // 若小程序与应用非同一主体,请使用推广任务,额外传递以下参数 @"micro_app_task_id" : @(123123), //小程序任务id @"agent_client_key" : @"xxx", //撮合中介clientKey };
注意
设置 Poi 锚点
目前支持第三方内容传入内容至抖音时携带 poi 信息,在发布页可以看到 poi 信息,成功发布视频后,在视频左下角带有 poi 入口。
req.poiID = @"poiid";
注意
该能力只支持投稿能力。
DouyinOpenSDKShareRequest 参数含义
参数 | 类型 | 是否必填 | 默认值 | 含义 |
shareAction | DouyinOpenSDKShareAction | 是 | DouyinOpenSDKShareTypePublishMedia | 分享动作类型 使用发布/转发能力时,设置为 DouyinOpenSDKShareTypePublishMedia |
localIdentifiers | NSArray | 是 | nil | 数组,由系统相册图片唯一标识 localIdentifier 构成 |
landedPageType | DouyinOpenSDKLandedPageType | 否 | DouyinOpenSDKLandedPageClip | 指定抖音打开页面 |
publishStory | BOOL | 否 | NO | 是否设置为转发到日常 |
mediaType | DouyinOpenSDKShareMediaType | 否 | DouyinOpenSDKShareMediaTypeImage | 当前内容类型 DouyinOpenSDKShareMediaTypeImage 纯图片 DouyinOpenSDKShareMediaTypeVideo 纯视频 DouyinOpenSDKShareMediaTypeMix 图片&视频混合 |
state | NSString | 否 | nil | 设置分享的上下文 建议传入 OpenAPI 中申请的 ShareID,分享结果会通过 Webhooks 进行回调。更多信息,请参见查询视频分享结果及数据 |
title | DouyinOpenSDKShareTitle | 否 | nil | 设置分享内容的标题 |
imageStickers | NSMutableArray<DouyinOpenSDKShareImageSticker *> | 否 | nil | 设置多张自定义图片贴纸 |
hashtagStickers | NSMutableArray<DouyinOpenSDKShareHashtagSticker *> | 否 | nil | 设置多张 HashTag 贴纸 |
mentionStickers | NSMutableArray<DouyinOpenSDKShareMentionSticker *> | 否 | nil | 设置多张@用户贴纸 |
poiStickers | DouyinOpenSDKSharePoiSticker | 否 | nil | 设置 POI 贴纸 |
quickFlashSticker | DouyinOpenSDKShareQuickFlashSticker | 否 | nil | 设置挑战贴纸 |
backgroundModel | DouyinOpenSDKShareBackground | 否 | nil | 转发到日常场景,设置背景图或背景色 |
daliyScale | NSNumber | 否 | nil | 转发到日常设置内容缩放比例 |
poiID | NSString | 否 | nil | 设置 POI 锚点 |
dailyContentType | DouyinOpenSDKShareDailyContentType | 否 | DouyinOpenSDKShareDailyContentTypeUnknown | 设置转发到日常内容类型 |
privateStatus | DouyinOpenSDKPrivateStatusType | 否 | DouyinOpenSDKPrivateStatusTypeUndefined | 设置公开范围 |
downloadType | DouyinOpenSDKDownloadType | 否 | DouyinOpenSDKDownloadTypeUndefined | 设置是否允许下载 |
feature | DouyinOpenSDKShareFeature | 否 | nil | 使用投稿能力时,当最终发布类型为图文时,设置是否转变为笔记 注:笔记能力在抖音 30.3 版本及以上生效 |
示例 Demo
常见问题
Q1 :拉起抖音立刻报错,错误码 respond.shareState 为 20003?
A: 一般都是包名错误,检查应用后台包名是否与当前应用包名是否匹配。clientKey 和 bundleID 要匹配。
Q2:用户分享完毕后没有跳回 App。
Q3:跳回 App 后,没有触发回调。
A:请参考 iOS 接入中第三部分,完成初始化 AppDelegate / SceneDelegate 部分。如果没有实现相关代码,SDK 拿不到抖音拉回 App 的 schema,无法得知前次分享发布结果,也就无法调用回调。
Q4:本地测试工程拉不起来抖音。
A:请参考 iOS 接入中第二部分,在开发者的工程中正确配置
LSApplicationQueriesSchemes
,同时请完全卸载开发者的 App 和抖音 App,同时在正常的网络环境下重新安装抖音。重新编译或下载开发者的 App。