移动应用

open SDK 概述

open SDK 下载

open SDK 接入

抖音分享

抖音投稿发布

抖音名片

抖音名片 Android接入

抖音名片 iOS接入

抖音授权

常见问题

网站应用

抖音名片 Android接入
收藏
我的收藏

使用场景

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

背景信息

作为日活超 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版本 ≥ 0.2.0.4 才支持名片功能。

整体流程

下面先介绍几个概念：

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

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

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

客态下调用名片接口

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

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

主态下调用名片接口

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

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

操作步骤

第一步：接入

接入名片功能前请确保 SDK 环境已配置完毕且获取了相关权限。具体操作请参见 Android 接入。

在接入部分一定要实现并注入下列实现：

•

网络实现（OpenNetworkService）

•

宿主实现（OpenHostInfoService）

•

票据实现（OpenHostTicketService）

同时确保在应用的管理后台配置了正确的包名等开发信息，路径为右上角控制台-移动应用-具体应用-设置-开发配置-开发信息。

第二步：使用

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

获取名片数据

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

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

val douYinProfileApi = DouYinOpenApiFactory.createOpenApi(activity, DouYinProfileApi::class.java)

val requestModel = RequestModel.Builder()
    .setShowOpenId(showOpenId) //必传，展示卡片用户
    .setHostOpenId(hostOpenId) // 如果当前用户无openId可不传。 如果hostOpenId跟showOpenId则为主态，不相等认为是客态。
    .build()
    
   douYinProfileApi?.fetchDouYinCardModel(activity, requestModel, object : ProfileCallback<OpenProfileModel> {
    override fun onFail(errCode: Int, msg: String?) {
        
    }

    override fun onSuccess(data: OpenProfileModel?) {
        
        }
    }
})

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

获取视频数据

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

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

val videoIds = mutableListOf<String>("videoIdxxx")  // 此处传入从 fetchDouYinCardModel 获取到视频 id 。
douYinProfileApi?.getVideoUrlList(activity, requestModel, videoIds, object : ProfileCallback<List<OpenVideoInfo>> {
    override fun onFail(errCode: Int, msg: String?) {
       
    }

    override fun onSuccess(data: List<OpenVideoInfo>?) {
        
    }
})

切换名片模式

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

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

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

// 切换名片模式，目前支持custom自定义模式 latest最新模式 hottest热度模式
douYinProfileApi?.switchCardShowMode(activity, requestModel, mode, object : ProfileCallback<Boolean> {
    override fun onFail(errCode: Int, msg: String?) {
       
    }

    override fun onSuccess(data: Boolean?) {
        
    }

})

设置封面视频

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

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

//设置封面视频id  videoID为返回的视频里面的VideoId
douYinProfileApi?.updateCoverVideo(activity, requestModel, videoID, object : ProfileCallback<Boolean> {
    override fun onFail(errCode: Int, msg: String?) {
        
    }

    override fun onSuccess(data: Boolean?) {
        
    }
})

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

//取消封面视频id  videoID为 -1
douYinProfileApi?.updateCoverVideo(activity, requestModel, "-1", object : ProfileCallback<Boolean> {
    override fun onFail(errCode: Int, msg: String?) {
        
    }

    override fun onSuccess(data: Boolean?) {
        
    }
})

跳转作品管理页

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

/**
 * 跳转作品管理页
 */
fun jumpVideoManager(activity: Activity, sourceOpenId: String, +): Boolean {
    val douYinOpenApi = DouYinOpenApiFactory.create(activity) ?: return false
    val supportApi = douYinOpenApi.isSupportApi(
        CommonConstants.SUPPORT.COMMON_ABILITY,
        CommonConstants.SUPPORT.COMMON_API.COMMON_TYPE_JUMP_NEW_PRODUCTION
    )
    if (!supportApi) {
        return false
    }
    val request = CommonAbility.Request()
    request.commonType = CommonAbility.COMMON_TYPE_JUMP_PRODUCTION
    request.mState = "state"
    request.callerLocalEntry = DouYinEntryActivity::class.java.canonicalName // 替换成自己回调类
    val data = JSONObject()
    try {
        data.put("from_open_id", sourceOpenId)
    } catch (e: JSONException) {
        e.printStackTrace()
    }
    request.data = data.toString()
    request.extras = Bundle()
    request.extras.putString("opensdk_type", "card")
    if (isHost) {
        request.extras.putString("launch_method", "personal_profile_card "); //主态下
    } else {
        request.extras.putString("launch_method", "others_profile_card_viewmore "); //客态下
    }
    return douYinOpenApi.openCommon(request)
}

注意：使用该能力需要应用有 jump.profile.video_selection 能力。

跳转抖音个人页

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

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

/**
 * 跳转抖音个人主页
 */
fun jumpDouYinUserProfile(activity: Activity, targetOpenId: String, isHost: Boolean): Boolean {
    val douYinOpenApi = DouYinOpenApiFactory.create(activity) ?: return false
    val supportApi = douYinOpenApi.isSupportApi(
        CommonConstants.SUPPORT.COMMON_ABILITY,
        CommonConstants.SUPPORT.COMMON_API.COMMON_TYPE_JUMP_NEW_PRODUCTION
    )
    if (!supportApi) {
        return false
    }
    val request = CommonAbility.Request()
    request.commonType = CommonAbility.COMMON_TYPE_JUMP_PROFILE
    request.mState = "state"
    request.callerLocalEntry = DouYinEntryActivity::class.java.canonicalName // 替换成自己回调类
    val data = JSONObject()
    try {
        data.put("target_open_id", targetOpenId)
    } catch (e: JSONException) {
        e.printStackTrace()
    }
    request.data = data.toString()
    request.extras = Bundle()
    request.extras.putString("opensdk_type", "card")
    if (isHost) {
        request.extras.putString("launch_method", "personal_profile_card"); //主态下
    } else {
        request.extras.putString("launch_method", "others_profile_card_viewmore"); //客态下
    }
    return douYinOpenApi.openCommon(request)
}

注意：使用该能力需要应用有 jump.profile 能力。

名片接口

public interface DouYinProfileApi extends IOpenApi {


    /**
     * 获取名片数据
     *
     * @param context
     * @param requestModel
     * @param callback
     */
    void fetchDouYinCardModel(Context context, RequestModel requestModel, ProfileCallback<OpenProfileModel> callback);

    /**
     * 获取播放视频相关数据
     * 调用该接口前需前置调用{@link DouYinProfileApi#fetchDouYinCardModel}接口成功
     *
     * @param context
     * @param requestModel 名片请求model
     * @param videoIds     视频itemId列表
     * @param callback     视频数据回调
     */
    void getVideoUrlList(Context context, RequestModel requestModel, List<String> videoIds, ProfileCallback<List<OpenVideoInfo>> callback);

    /**
     * 切换名片模式，不同模式获取到的视频可能不同
     *
     * @param context
     * @param requestModel 名片请求model
     * @param mode         名片模式，目前支持custom自定义模式 latest最新模式 hottest热度模式
     * @param callback     回调接口
     */
    void switchCardShowMode(Context context, RequestModel requestModel, String mode, ProfileCallback<Boolean> callback);

    /**
     * 设置封面视频，后续可以从{@link DouYinProfileApi#getVideoUrlList(Context, RequestModel, List, ProfileCallback)} 获取视频数据
     *
     * @param context
     * @param requestModel 名片请求model
     * @param videoId      需要keep住的视频id
     * @param callback     回调接口
     */
    void updateCoverVideo(Context context, RequestModel requestModel, String videoId, ProfileCallback<Boolean> callback);
}

数据结构体

OpenProfileModel

public class OpenProfileModel {

    public int errCode; //错误码
    public String errMsg;  //错误信息

    public int subErrCode; //子错误码
    public String subErrMsg; //子错误信息

    public OpenBaseInfo baseInfo; //名片个人数据

    public ArrayList<OpenVideoInfo> openVideoInfos;  //视频数据列表
}

OpenBaseInfo

public class OpenBaseInfo {
    public String nickName; // 用户昵称
    public String avatar; // 用户头像
    /**
     * 抖音号
     */
    public String uniqueId;
    /**
     * 个人简介
     */
    public String signature;

    //粉丝数量
    public long fanCount;
    //作品总获赞数
    public long videoDiggCount;
    //是否私密账号
    public boolean isSecret;
    //用户是否自定义过视频
    public boolean hasSetCustomVideo;

    // latest 展示最新视频
    // hottest 展示最热
    // custom 展示自定义视频
    public String showType = "latest";

    public int customVideoCount = 0; // 自定义视频数量

    /**
     * 被访问用户是否授权user.card.video
     */
    public boolean authCardVideo;
}

OpenVideoInfo

public class OpenVideoInfo {
   
    public String videoId;  //视频id
    public String title;  //视频标题
    /**
     * 是否设置的封面置顶视频
     */
    public boolean isClientTop;
    //视频宽
    public int videoWidth;
    //视频高
    public int videoHeight;
    //封面地址
    public List<String> coverUrlList;
    //点赞数
    public long diggCount;

    //视频播放地址
    public List<String> videoUrlList;
}

常见错误码

错误码	错误码含义
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无效

抖音名片 Android接入收藏我的收藏