移动应用

open SDK 概述

open SDK 下载

open SDK 接入

抖音分享

抖音投稿发布

抖音名片

抖音名片 Android接入

抖音名片 iOS接入

抖音授权

常见问题

网站应用

抖音名片 iOS接入

我的收藏

使用场景

本能力适用于通过使用抖音短视频授权，获取用户名片信息。

背景信息

作为日活超 6 亿的国民应用，用户在抖音记录生活、丰富社交，沉淀了大量有价值的内容，而这些内容聚合起来，便是每个人独一无二的“名片”。为了让用户更便捷地在各类应用下展示自己的社交身份与形象，抖音为第三方移动 App 提供了用户社交名片开放能力，方便开发者在其应用下快速拓展账号服务，帮助用户建立有价值的关注和社交关系，提升用户在开发者应用下的留存。详细能力介绍可以查看抖音名片 SDK。

前提条件

•名片能力需要前置申请一下权限。其中 user.card.profile、user.card.video 两个权限需要用户授权，用户授权同意之后才能获取到用户名片与视频信息。

scope	描述	是否需要用户授权	备注
open.user.card.parent	抖音名片	是	开发者获取用户账号＋作品数据的必要权限组，获取成功后支持在开发者应用下渲染并展示抖音用户信息 •user.card.profile（获取主态用户账号数据） •user.card.video（获取主态用户视频数据） •user.card.profile.guest（获取客态用户账号数据） •user.card.video.guest（获取客态用户视频数据）
open.jump.user_profile	跳转作品管理页	否	第三方应用通过 SDK 拉起抖音 App 并跳转指定页面的必要鉴权
jump.profile	跳转抖音个人页	否	第三方应用通过 SDK 拉起抖音 App 并跳转指定抖音号主页的必要鉴权

•需要手动安装包含名片功能的 SDK 包，包含名片功能的 SDK 包可以在 iOS 接入处下载。

整体流程

下面先介绍几个概念：

主态：当前用户与被查看用户是同一个用户。

客态：当前用户与被查看用户非同一个用户。

1.开发者在拉起授权时需要额外传入 user.card.profile、user.card.video 两个 scope，在用户同意后获取 code。给到服务端调用 access_token 接口获取 access_token。详细流程参考授权。

2. 客态下调用名片接口。

客态主需要开发者实现获取 client_code 接口，将 client_code 返回给 SDK。

注意：client_code 接口因为使用 client_secret 因此不能在客户端调用，需要在服务端调用。

3.主态下调用名片接口。

主态与客态基本流程一致，不同点在于回调需要开发者服务端通过用户的 access_token 获取到 access_code 并返回给 SDK。

注意：access_code 接口因为使用 access_token 因此不能在客户端调用，需要在服务端调用。

操作步骤

第一步：SDK接入与初始化

工程接入：

手动安装包含名片功能的 SDK 包，包含名片功能的 SDK 包可以在 iOS 接入处下载。

需要在工程配置中的LSApplicationQueriesSchemes前50位配置 douyinOpenExternalProfileV1

票据接口初始化

需要在合适的时机，在调用名片能力之前注册主客态方法。

票据接口初始化
[[DYOpenExternalTicketService sharedInstance] registerClientKey:[self getClientKey]
                                             requestClientCodeBlock:^(NSString * _Nonnull clientKey, DYOpenFinishRequestClientCodeBlock _Nonnull finishRequestBlock) {
        // 宿主调用自己的服务端接口获取clientCode，然后回调给SDK
        !finishRequestBlock ?: finishRequestBlock(clientCode, error);
}];
    // 主态
    [[DYOpenExternalTicketService sharedInstance] registerClientKey:[self getClientKey]  requestAccessCodeBlock:^(NSString * _Nonnull clientKey, DYOpenFinishRequestAccessCodeBlock  _Nonnull finishRequestBlock) {
        // 宿主调用自己的服务端接口获取accessCode，然后回调给SDK，openid和accessCode是对应的，不要传错
        !finishRequestBlock ?: finishRequestBlock(accessCode, openid, nil);
 }];

第二步：使用

目前对外提供了以下接口，下面详细介绍每个接口的功能与使用方式。

注意
以下接口中的 customMaxVideoCount 为保留入参，如无联动抖音的实验需求，可以填写非0数字，但实际下发的视频数量由抖音决定。

获取名片数据

该接口主要用来用户的名片数据与视频数据。

主要使用场景为在需要展示用户个人信息和视频封面等场景。

/// 获取名片数据
/// - Parameters:
///   - context: 请求主客态上下文
///   - completion: 结果回调
+ (void)fetchProfileModelWithContext:(DouyinOpenSDKExternalProfileContext *)context
                 customMaxVideoCount:(NSNumber *)customMaxVideoCount
                           completion:(void(^_Nullable)(NSError *error, DouyinOpenSDKExternalProfileModel *model))completion;

注意
获取名片个人数据部分需要用户授权 user.card.profile ，获取名片视频数据需要用户授权 user.card.video。如果用户仅授权 user.card.video 那么将不会返回视频数据，如果用户没有授权 user.card.profile，那么将会报错。

获取视频数据

该接口主要用于获取视频数据，包括视频封面、播放链接等数据。

主要使用场景为在播放视频前传入视频 id 调用该接口获取最新的播放链接，避免因为时效性导致播放链接失效无法播放。

/// 获取视频列表
/// - Parameters:
///   - context: 请求主客态上下文
///   - videoIdList: 视频videoID列表
///   - completion: 结果回调
+ (void)getVideoURLListWithContext:(DouyinOpenSDKExternalProfileContext *)context
                       videoIDList:(NSArray<NSString *>*)videoIdList
               customMaxVideoCount:(NSNumber *)customMaxVideoCount
                        completion:(void(^ _Nullable)(NSError *error, NSArray<DouyinOpenSDKExternalProfileVideoModel *> *list))completion;

切换名片模式

该接口主要用于切换名片模式，仅主态下可以调用。

目前名片提供三种模式：热度模式（hottest），在此模式下会返回热度最高的几条视频数据；最新模式（latest），在此模式下会返回最新的几条视频数据；自定义模式（custom），在此模式会返回用户在视频管理页设置的视频数据。

主要使用场景为用户跳转名片管理页设置自定义视频成功后切换到自定义模式。开发者也可以自行切换模式。

/// 切换名片模式，不同模式获取到的视频可能不同
/// - Parameters:
///   - context: 请求主客态上下文
///   - showType: 名片模式，目前支持custom自定义模式 latest最新模式 hottest热度模式
///   - completion: 结果回调
+ (void)switchCardShowModeWithContext:(DouyinOpenSDKExternalProfileContext *)context
                             showType:(DYOpenExternalProfileShowType)showType
                           completion:(void(^ _Nullable)(NSError *error))completion;

设置封面视频

该接口主要用于设置封面视频，仅主态下可以调用。在设置了封面视频后 fetchDouYinCardModel 接口会额外返回设置的封面视频数据。

主要场景为设置封面，需要获取用户的特定视频数据。

注意
如果想取消掉封面视频可以通过 videoID 参数传入 -1。

/// 设置固定视频
/// - Parameters:
///   - context: 请求主客态上下文
///   - videoID: 视频ID（如果要取消封面视频，videoID传入-1）
///   - completion: 结果回调
+ (void)updateCoverVideoWithContext:(DouyinOpenSDKExternalProfileContext *)context
                            videoID:(NSString *)videoID
                         completion:(void(^ _Nullable)(NSError *error))completion;

跳转作品管理页

该接口主要用于跳转到抖音的作品管理页，让用户可以自定义选择展示视频。在用户自定义选择视频后记得切换到自定义模式，这样才能获取到用户自定义的视频数据。

/// 跳转抖音的名片管理页面（若要使用，请在前50位schema配置douyinOpenExternalProfileV1）
/// - Parameters:
///   - openId: 当前用户openID
///   - customMaxVideoCount: 自定义视频数量
///   - completion: 跳转回调
+ (void)jumpToAlbumWithWithOpenId:(NSString *)openId
              customMaxVideoCount:(NSNumber *)customMaxVideoCount
                       completion:(DouyinOpenSDKExternalJumpCompletion)completion;

跳转抖音个人页

该接口主要用于抖音的个人页。

主要场景为在查看他人名片时，可以跳转到抖音查看用户的抖音个人主页，查看更多视频与数据。

/// 跳转主客态个人页（若要使用，请在前50位schema配置douyinOpenExternalProfileV1）
/// - Parameters:
///   - openId: 当前用户openID
///   - targetOpenId: 目标用户openID
///   - extraParams: 额外数据（王者需要主动传入opensdk_type = card（用于区分细分场景））
///   - completion: 跳转回调
+ (void)jumpToProfileWithOpenId:(NSString *)openId
                   targetOpenId:(NSString *)targetOpenId
                    extraParams:(nullable NSDictionary <NSObject *, id> *)extraParams
            customMaxVideoCount:(NSNumber *)customMaxVideoCount
                     completion:(nullable DouyinOpenSDKExternalJumpCompletion)completion;

强制使用Schema模式跳转

注意
由于iOS系统的universal link方案存在一定跳转失败概率，所以新增降级schema拉起的设置。
不建议在正常情况下设置该参数，universal link 能保证如果能拉起应用，一定能拉起抖音App。

[DouyinOpenSDKApplicationDelegate sharedInstance].focusUseSchemaJump = YES;

数据结构体

DouyinOpenSDKExternalProfileModel

@interface DouyinOpenSDKExternalProfileModel : NSObject

@property (nonatomic, copy) NSString *nickName;
@property (nonatomic, copy) NSString *uniqueId; // 抖音号
@property (nonatomic, copy) NSString *signature; // 个人简介
@property (nonatomic, copy) NSString *avatarURLString;
@property (nonatomic, assign) NSInteger fanCount;
@property (nonatomic, assign) NSInteger videoDiggCount;
@property (nonatomic, assign) NSInteger isSecret;
@property (nonatomic, assign) BOOL hasSetCustomVideo;
@property (nonatomic, copy) NSString *showType;
@property (nonatomic, assign) NSInteger customVideoCount;
@property (nonatomic, assign) BOOL authCardVideo;
@property (nonatomic, copy) NSArray<DouyinOpenSDKExternalProfileVideoModel*>* profileVideoModels;
@property (nonatomic, assign) BOOL isViewMore; // 是否展现更多按钮

@end

DouyinOpenSDKExternalProfileVideoModel

@interface DouyinOpenSDKExternalProfileVideoModel: NSObject

@property (nonatomic, strong) NSString *videoId;
@property (nonatomic, strong) NSString *title;
@property (nonatomic, assign) NSInteger height;
@property (nonatomic, assign) NSInteger width;
@property (nonatomic, strong) NSArray<NSString *> *coverURLList; // 封面地址
@property (nonatomic, assign) NSInteger diggCount; // 点赞数
@property (nonatomic, strong, nullable) NSArray<NSString *> *videoURLList; // 视频播放URL
@property (nonatomic, assign) BOOL isClientTop; // 是否是封面视频

@end

常见错误码

错误码	错误码含义
40001	未知错误
40002	初始化失败
40003	未实现相关能力
40004	参数错误
40005	网络错误
41001	获取clientCode失败
41002	获取clientTicket失败
41101	获取accessCode失败
41102	获取accessTicket失败
28001003	access_token无效
28001005	系统内部错误，请重试
28001008	access_token过期,请刷新或重新授权
28001010	未知错误
28001012	用户未授权相关scope
28001013	目标用户未授权相关scope
28001014	应用未授权任何能力
28001016	当前应用已被封禁或下线
28001018	应用未获得该能力
28001019	应用该能力已被封禁
28001024	ClientTicket无效