抖音开放平台Logo
开发者文档
“/”唤起搜索
控制台
  • JS API 列表
  • 基础
  • TTML
  • 网络
  • 媒体
  • 地图
  • 文件
  • 数据缓存
  • 地理位置
  • 设备
  • 画布
  • 界面
  • 页面导航
  • 开放接口
  • 登录
  • 用户信息
  • 广告
  • 营销能力
  • 支付
  • 分享
  • 小程序跳转
  • 抖音视频能力
  • 收货地址
  • 设置
  • 授权
  • 评价能力
  • 数据分析
  • 视频拍摄器
  • 引导关注
  • 订阅消息
  • 电商插件能力(即将废弃)
  • 隐私信息授权
  • web化
  • 转发和挂载
  • 概述
  • 分享
  • ShareOption
  • ShareParam
  • 视频发布和挂载
  • 直播挂载
  • 视频拍摄器
  • tt.showShareMenu
  • tt.hideShareMenu
  • tt.navigateToVideoView
  • 侧边栏能力
  • 直播能力
  • AI/AR能力
  • 安全能力
  • 行业开放
  • 第三方平台
  • 其它
  • 生活服务(即将废弃)
  • 分享

    分享功能是提供给开发者,在转发出去的小程序被二次打开的时候获取信息的能力。设置信息的流程见转发和挂载概述。
    基础库 1.0.0 开始支持本接口。使用时可用 tt.canIUse 判断是否可用。
    开发者最终传递给发布器的数据,可以根据约定传入部分自定义数据。属性如下:
    属性
    类型
    默认值
    是否必填
    说明
    最低支持版本
    channel
    string
    ​
    否
    转发内容类型
    1.0.0
    taskIds
    string[]
    ​
    否
    分享任务模板 id,通过分享任务服务端接口创建。
    用户完成分享后会在success回调内返回当前用户的对应任务完成信息;
    2.96.0
    imMsgType
    number
    ​
    否
    在抖音IM分享时决定是否使用新版分享卡片样式,其中 1 代表使用新样式,0 代表使用旧样式,具体效果参考分享能力介绍。
    其中新版分享卡片的图片(imageUrl)分辨率为 720*405,旧版为 400*400,因此开启时需要针对最低支持的基础库版本做前后兼容。
    2.86.0
    templateId
    string
    ​
    否
    分享素材模板 id,指定通过平台审核的 templateId 来选择分享内容,需在平台设置且通过审核。
    1.0.0
    desc
    string
    ​
    否
    分享文案,不传则默认使用后台配置内容或平台默认。
    1.0.0
    title
    string
    ​
    否
    转发标题,不传则默认使用后台配置或当前小程序的名称。注意配置的 title 需要经过小程序的内容安全检测,只有检测通过后的文案才会正常展示,否则展示小程序默认文案。头条 App 拍视频不支持设置 title。
    1.0.0
    imageUrl
    string
    ​
    否
    转发显示图片的链接,可以是网络图片路径或本地图片文件路径或相对代码包根目录的图片文件路径。当发布视频内容时,不支持通过 imageUrl 参数设置分享图片。
    imMsgType:1,推荐使用 720*405 分辨率图片。imMsgType:0,使用 400*400 分辨率图片;
    注意配置的 URL 需要经过小程序的内容安全检测,只有检测通过后的图片才会正常展示,否则展示小程序默认图标。
    1.0.0
    path
    string
    ​
    否
    转发路径
    1.0.0
    extra
    object
    ​
    否
    附加信息,只有分享视频内容时,才可以通过 extra 设置附加信息
    1.0.0
    success
    Function
    ​
    否
    分享成功后执行的回调函数,当传入taskIds时,会返回分享任务结果 taskResult
    1.0.0
    fail
    Function
    ​
    否
    分享失败或者用户取消发布器后执行的回调函数
    1.0.0
    complete
    Function
    ​
    否
    分享完成(无论成功与否)后执行的回调函数
    1.0.0

    channel

    值
    说明
    -
    默认分享方式, channel 为空字符串或者不传(undefined)
    article
    发布图文内容,仅头条 App 支持
    video
    发布视频内容,后续此字段不再继续迭代,「视频发布和挂载」请参考 视频发布和挂载 进行接入。
    token
    口令分享,生成一串特定的字符串文本,仅头条 App 支持
    注意,如果 ShareOption 中的 channel 不为空,则设置 ShareParam 的 channel 无效。

    extra

    当发布视频内容时(channel 为 video,或者用户通过菜单中的选项选择了视频分享),可以通过 extra 设置附加信息:
    属性
    类型
    默认值
    说明
    withVideoId
    boolean
    ​
    是否支持跳转到播放页, 以及支持获取视频信息等接口 (为 true,且视频中携带了小程序锚点,才会在 success 回调中带上 videoId),后续此字段不再继续迭代,「视频发布和挂载」请参考 视频发布和挂载 进行接入。
    videoPath
    string
    ​
    视频地址 ,分享一个本地视频,后续此字段不再继续迭代,「视频发布和挂载」请参考 视频发布和挂载 进行接入。
    videoTopics
    array
    ​
    视频话题(仅抖音支持) ,目前由 hashtag_list 代替,为保证兼容性,建议同时填写两个,后续此字段不再继续迭代,「视频发布和挂载」请参考 视频发布和挂载 进行接入。
    createChallenge
    boolean
    false
    是否分享为挑战视频 ( 仅头条支持 )
    video_title
    string
    ""
    生成输入的默认文案,后续此字段不再继续迭代,「视频发布和挂载」请参考 视频发布和挂载 进行接入。
    hashtag_list
    array
    ​
    视频话题(仅抖音支持),后续此字段不再继续迭代,「视频发布和挂载」请参考 视频发布和挂载 进行接入。
    ecReferralParams
    object
    ​
    裂变活动参数,具体属性如下表「extra.ecReferralParams 参数说明」
    group_activity_id
    string
    ​
    群聊活动参数(仅抖音支持),开发者可自定义,最低支持版本3.64.0

    extra.ecReferralParams 参数

    属性
    类型
    默认值
    说明
    最低支持版本
    activityId
    string
    --
    活动id
    2.52.0
    shopId
    string
    --
    小程序绑定的抖音小店shopId
    2.52.0

    success 回调

    属性
    类型
    说明
    最低支持版本
    errMsg
    string
    shareAppMessage:ok
    1.0.0
    videoId
    string
    分享出去的视频id,当传入了withVideoId且视频中携带了小程序锚点,才会返回,后续此字段不再继续迭代,「视频发布和挂载」请参考 视频发布和挂载 进行接入。
    1.48.1
    type
    string
    目前支持video 和 image ,代表当前展示的是视频还是图文,仅在拍抖音场景下返回,后续此字段不再继续迭代,「视频发布和挂载」请参考 视频发布和挂载 进行接入。i
    3.1.0
    taskResult
    TaskResult[]
    当前用户的分享任务结果,当shareParams有传入taskIds才会返回
    2.96.0

    TaskResult

    属性名
    ​
    类型
    说明
    最低支持版本
    taskId
    string
    任务id
    2.96.0
    completed
    boolean
    当前用户在该任务的状态,true代表已全部完成,false代表未完成
    2.96.0
    successCount
    number
    当前用户在该任务的进度
    2.96.0
    increaseCount
    number
    本次分享带来的任务完成人数的进度更新
    2.96.0
    isValid
    boolean
    任务是否还在有效期
    2.96.0
    errNo
    number
    错误码
    2.96.0
    errMsg
    string
    错误信息
    2.96.0

    分享内容优先级

    支持两种形式来指定转发的内容(图片、标题、文案),最终按照优先级规则进行选择, 详情参考内容转发。
      1.代码指定分享内容(title、desc、imageUrl)
      2.指定审核通过的模板素材 templateId
    场景
    优先级
    端内分享
    代码指定分享内容 > 指定模板 > 平台默认
    端外分享
    指定模板 > 平台默认

    内容安全

    当开发者发现虽然已成功配置分享内容,但是调试时内容无法生效时,有可能是分享内容触发了内容安全检测失败,导致分享失败。发生这种情况时,开发者可以尝试对分享内容进行内容安全检测,具体操作手段见内容安全检测

    Bug & Tip

      •Tip:端外分享不支持通过代码设置自定义分享内容;
      •Tip:videoTopics 即将废弃,应使用 hashtag_list 代替;或者同时设置以保证兼容性;
      •Tip:分享时,在 channel 是 "video"的情况下,如果 videoPath 是不存在会拉起摄像头拍摄界面;
      •Tip:如果需要获取视频信息或者跳转视频播放页,以及获取抖音视频排行榜时,需要填写 withVideoId 为 true;
      •Tip:配置的 imageUrl 以及 title 需要经过小程序的内容安全检测,只有检测通过才会正常展示,否则展示小程序默认内容;
      •Tip:分享形式除了使用小程序页面右上角的“更多”中的转发按钮外,发布视频选择小程序也视为分享行为,也会执行 Page.onShareAppMessage ,若需要在发布视频选择小程序时不计为分享裂变活动,可在 ShareOption.channel值为 video时 ,不传 extra.ecReferralParams。
    ​