# 介绍

短剧播放器是微信官方为微短剧类目小程序提供的播放器插件，旨在帮助短剧开发者降低开发及运营成本，提供短剧行业的运营组件能力，提升微信内短剧播放质量及优化用户体验。 开发者可引入短剧播放器插件后，基于自身需求进行开发配置。

具体介绍

短剧播放器介绍

接入示例

代码示例

# 接入流程

为了更好地使用短剧播放器插件，您需要按照以下步骤进行接入：

1.剧集内容授权：播放方小程序需要获得提审方剧集的授权，详见：

(1)剧目授权

(2)账号授权

2.申请添加插件：接入短剧播放器插件之前，您需要先完成插件的添加申请。

添加方式1:MP-设置-第三方设置-插件管理-添加插件

输入插件appid:wx94a6522b1d640c3b,即可添加完成。

添加方式2:开发者工具添加，详见3.1 插件如何引入

3.插件接入：开始进行插件的接入开发，详见文档 3.基础接入

4.其他自定义开发：除了基本的插件接入，您还可以根据自身需求接入播放器所提供的运营能力以及进行其他自定义开发，为用户提供更多的功能和特性。详见文档 4.运营能力

# 基础接入

在接入之前，可以先提前了解下面的问题：

1. 在开发者工具调试时，需要先去掉app.json的设置"lazyCodeLoading": "requiredComponents"，否则可能会碰到黑屏，或者是报错Plugin module "__wx__/plugin-private-api" is not defined.。
2. 有些使用框架的开发者，例如uniapp，如果碰到自定义运营区域组件，或者充值组件无法渲染的问题，可能是该组件被框架删除了。可通过创建一个空的页面，去引用对应的组件，页面的json文件可参考

{
  "usingComponents": {
    "charge-dialog": "/components/charge-dialog/charge-dialog",
    "open-area-left": "/components/open-area-left/open-area-left",
    "open-area-left-side": "/components/open-area-left-side/open-area-left-side",
  }
}

# 插件如何引入

首先在小程序的 app.json 文件中添加插件的引入配置，示例代码如下：

{
  "plugins": {
    "playlet-plugin": {
      "version": "latest",
      "provider": "wx94a6522b1d640c3b"
    }
  }
}

"provider"字段为插件提供方的appid，设置为"wx94a6522b1d640c3b"即可。请确保将 "version" 字段设置为 "latest"，以使用最新版本的插件。

在开发者工具Console里点击「添加插件」即可自动通过。 具体的接入流程可参考下面的步骤：

# 插件接入流程

下面的接入流程涉及的一些字段的含义，先提前说明下：

• srcAppid: 提审方 appid，通过小程序媒资管理上传了剧目的账号 appid。
• dramaId: 剧目 ID，通过小程序媒资管理提审的剧目 id。
• serialNo: 剧集 ID，从1开始递增，比如第 1 集则 serialNo 是 1，注意这里跟媒资管理的 mediaNo 是不一样的。
• playerId: 播放器页面实例的唯一 ID，由于可能页面栈上会存在多个播放器页面，所以需要通过这个唯一的 ID 来区分不同的页面，例如从播放器的推荐跳转到另外一个剧。

插件提供的能力说明：

• 插件提供了播放器页面，接入后可以通过播放器页面的路径使用，播放器的路径前缀为 plugin-private://wx94a6522b1d640c3b/pages/playlet/playlet。
• 播放器页面和小程序之间有比较多的逻辑交互，例如某一集是否能解锁观看，需要开发者提供，插件提供了一些接口来让小程序去交互。接口通过 const playletPlugin = requirePlugin('playlet-plugin') 返回的插件实例来调用。
• 点击可查看详细接口文档

播放器里面是否可解锁等数据，需要开发者提供，开发者可以参考下面的步骤进行接入。

# 跳转到播放器页面

在开发者的页面中跳转到播放器页面，请参考以下示例代码：

Page({
  onJumpPlayer() {
    const { srcAppid, dramaId } = this.data
    const extParam = encodeURIComponent('a=b&c=d') // 需要 encodeURIComponent

    // 跳转到短剧播放页
    wx.navigateTo({
      url: `plugin-private://wx94a6522b1d640c3b/pages/playlet/playlet?dramaId=${dramaId}&srcAppid=${srcAppid}&serialNo=${serialNo}&extParam=${extParam}`
    })
  },
})

播放器页面接收 srcAppid 参数、dramaId 参数和 serialNo 等参数，其中：

• dramaId 是开发者通过媒资管理的 API 上传的剧目 id，必填
• srcAppid 是提审方的 appid，必填
• serialNo 是指定播放的剧集id，从 1 开始递增（不是媒资管理的 mediaNo），选填，如果不传，进入播放器页面则会从上次播放的剧集开始继续播放
• extParam 是可选的扩展参数，选填，PlayletManager.getInfo() 可获得传入的此参数，分享的时候也会带上此参数，可以作为上报的参数使用。

当进入播放页时，会触发插件的 onPageLoad 回调给开发者。

# 监听播放页加载

const playletPlugin = requirePlugin('playlet-plugin')

App({
  onLaunch() {
    playletPlugin.onPageLoad(info => {
      const pm = playletPlugin.PlayletManager.getPageManager(info.playerId)

      // 初始化剧集列表状态
      pm.setCanPlaySerialList({
        serialList: [{
          start_serial_no: 1,
          end_serial_no: 4,
          status: 1, // 1-4 集解锁
        }, {
          start_serial_no: 5,
          end_serial_no: 20,
          status: 2, // 5 - 20 集未解锁
        }],
        freeList: [], // 免费剧集
      })

      // 用户进入未解锁的剧集时会触发此事件
      pm.onCheckIsCanPlay(param => {
        const serialNo = param.serialNo
        if (serialNo <= 10) {
          // 10 集以内解锁
          pm.isCanPlay({
            serialNo,
            serialList: [{
              start_serial_no: serialNo,
              end_serial_no: serialNo,
              status: 1,
            }],
          })
        } else {
          // 其他剧集不解锁 并展示支付弹窗
          pm.isCanPlay({
            serialNo,
            serialList: [{
              start_serial_no: serialNo,
              end_serial_no: serialNo,
              status: 2,
            }],
          })
          pm.showChargeDialog()
        }
      })
    })
  },
})

# 实现后台接口初始化剧集状态

在上述代码中，setCanPlaySerialList({ serialList, freeList }) 接口来初始化剧集状态。

其中 serialList 是剧集解锁状态列表，类型为 Array<SerialItem>，SerialItem 定义如下：

freeList 参数是免费剧集列表，类型为 Array<FreeItem>，FreeItem 定义如下：

注意：免费剧集配置与“微短剧”优质小程序流量主激励政策有重要关联；它是已解锁剧集的一个特殊状态，和普通的已解锁剧集只有 ui 上的不同。免费剧集的 ui 如下：

# 解锁剧集

当用户进入到未解锁的剧集时，会触发开发者使用 onCheckIsCanPlay 方法注册的回调函数。开发者需要在此回调函数中判断用户是否可以解锁该集。

开发者可以调用 isCanPlay({ serialNo, serialList }) 方法来设置该集的解锁状态，同时消除播放器的 loading。此处的 serialList 定义和 setCanPlaySerialList 的 serialList 参数一致。

开发者将该集设置为解锁后，播放器便会自动开始播放该集内容；如果开发者将该集仍然设置为未解锁，播放器便会显示相应的未解锁界面，提示用户需要解锁才能继续观看。

# 充值组件

充值组件是一个自定义组件，会渲染在播放页面的半屏弹窗中。开发者需要自己实现此组件的充值逻辑，充值组件存在最大高度限制，如果内容高度超过弹窗高度，需使用 scroll-view 组件实现滚动。开发者需提前获取到渲染弹窗内容所需要的数据，避免在弹窗拉起的时候内容变化导致弹窗高度发生变化。

1. 在 app.json 文件中，需要定义组件 charge-dialog，指向开发者自己实现的充值组件。示例代码如下：

{
  "usingComponents": {
      "charge-dialog": "/components/charge-dialog/charge-dialog"
  },
  "plugins": {
    "playlet-plugin": {
      "version": "latest",
      "provider": "wx94a6522b1d640c3b",
      "genericsImplementation": {
        "playlet": {
          "charge-dialog": "/components/charge-dialog/charge-dialog"
        }
      }
    }
  }
}

注意：如果是在分包引入插件，上面定义的充值组件也需要在分包内。

2. 开发者可以通过 showChargeDialog() 方法来显示充值弹窗，并通过 onShowChargeDialog(func) 以及 onHideChargeDialog(func) 方法注册显示/隐藏弹窗的事件回调函数。 充值完成后，开发者onShowChargeDialog(func) 方法注册显示弹窗的事件回调函数。当充值弹窗拉起时，会触发此回调函数。
3. 可以调用 hideChargeDialog() 来关闭弹窗。
4. 可以调用 updateChargeDialogHeight({ height: 500 }) 来设置弹窗高度。
5. 可以调用 updateChargeDialogInfo({ isTransparentBackground: true }) 来设置充值弹窗背景透明。
6. 播放器会将 srcAppid、dramaId、serialNo、playerId、extParam 作为属性传递给 charge-dialog 组件。开发者可以在组件中定义这些属性，并根据 serialNo 的变化，获取不同的充值数据进行渲染。

Component({
  properties: {
    playerId: {
      type: String,
      value: ''
    },
    srcAppid: {
      type: String,
      value: ''
    },
    dramaId: {
      type: String,
      value: ''
    },
    serialNo: {
      type: Number,
      value: 0
    },
    extParam: {
      type: String,
      value: ''
    },
  },
  observers: {
    serialNo(serialNo) {
      // 当集数发生改变的时候，触发此函数
    }
  }
})

7. 事件系统

充值组件是在播放器页面引入的，开发者无法通过在 wxml 里面注册相关的事件，因此插件提供了事件函数，可使用下面的 onCustomEvent 注册事件，emitCustomEvent 触发事件

// 在充值组件内触发自定义事件
pm.emitCustomEvent(name, args)

// 在其他地方监听充值组件触发的自定义事件
pm.onCustomEvent(name, func)

# 数据加密方案

上述例子中的 setCanPlaySerialList 和 isCanPlay 方法的调用都是直接传递剧集解锁信息给播放器来实现剧集解锁状态的变更。如果开发者对剧集解锁状态的变更有更高的安全性要求且能承担一定的性能损失，还可以选用传递加密数据的方式来实现剧集解锁。

注意：选用加密方案的话安全性相对较高，但性能会有所损耗，可根据实际情况选用对应方案。

具体调用方式如下：

// 无需加密方案
pm.setCanPlaySerialList({
  serialList: [{
    start_serial_no: 1,
    end_serial_no: 4,
    status: 1, // 解锁
  }, {
    start_serial_no: 5,
    end_serial_no: 20,
    status: 2, // 未解锁
  }],
})
pm.onCheckIsCanPlay(param => {
  pm.isCanPlay({
    serialNo: 15,
    serialList: [{
      start_serial_no: 15,
      end_serial_no: 15,
      status: 1, // 解锁
    }],
  })
})

// 加密方案
const data = await getEncryptData() // getEncryptData 需要开发者自行实现
pm.setCanPlaySerialList({
  data,
})
pm.onCheckIsCanPlay(async param => {
  const data = await getEncryptData() // getEncryptData 需要开发者自行实现
  pm.isCanPlay({
    serialNo: 15,
    data,
  })
})

其中 data 参数是加密后的数据，即 LockDataReq 对象经过 JSON.stringify，然后再加密后得到的字符串。LockDataReq 定义如下：

注意：接入了免开发激励视频广告解锁必须采用加密方案来调用 setCanPlaySerialList 和 isCanPlay 方法。

# 具体加密流程

上述加密方案中的加密数据需要经过在开发者后台使用 session_key 的前16个字节作为密钥加密（不足 16 个字节后面补零），加密算法 AES-128-ECB。

加密步骤：

1. 调用微信 api 获取当前登录用户的最新 session_key

2. 使用 LockDataReq 结构组装待加密的明文数据（LockDataReq 定义见上述介绍）
3. 将 LockDataReq 转成 json 字符串 data
4. 使用 AES-128-ECB 算法对 data 进行加密，密钥是第 1 步获取的 session_key 的前 16 个字节
5. 对 data 加密后的密文进行 base64 编码

示例：

1. LockDataReq 转成 json 的示例（以下示例表示解锁第 10-12 集,不解锁第 13-15 集）

{"openid":"xJad239kjafkjakdjfe","src_appid":"wx98293892389823","drama_id":"21212","serial_list":[{ "start_serial_no":10,"end_serial_no":12,"status":1},{"start_serial_no":13,"end_serial_no":15,"status":2}], "data_expire_at":1703474855}

2. 加密示例

密钥是 89283sdkj1212121212，将上述示例加密后的 base64 编码结果：

LHb+riG/WsCP8wqQEIvJxCx59exL+Wjf23R/pTIbC9gZo3yrUrMMoqIb3/zviK0jtt2HBTk4Eke/bmSD/qKwfY277NK6YNv9wML8+loNnjIkPJHj3DHUALEcwxBTOUVqgTBNTFimtdU7qwkqMIMU1RSlQR+U9CFckbX46mCQoyA8VssxP5ej16+WIcnVqGbkZQdI5hoWZqvwRdnQtMV3s5ZDlGxxYS75XoTYMNdNYOS6bA9jt4K1AUWuEQcOw8ygs4a8EqYbwnA7uD6Ks+54O6xtEXmLyr5uPZKXcbyzjWs17+odJHI+e0gU5o79e3I6

开发者可以使用解密代码解密以上实例，验证加解密逻辑是否正确

# 其它开放接口

# 暂停/继续播放

PlayletManager.play()和PlayletManager.pause()

# 获取剧目信息

getInfo()获取到当前剧的相关信息，具体返回的数据结构如下：

PS：以上为固定常用字段，其他页面路径上的参数也会在此处返回。

# 更换剧目

// 请将{srcAppid}替换为提审方appid，{dramaId}替换为真实剧id
PlayletManager.changeDrama({
    queryString: 'srcAppid={srcAppid}&dramaId={dramaId}'
})

# 数据上报

PlayletManager.onDataReport(func)

开发者可通过此方法注册回调函数获得数据上报相关的回调，其中event表示上报的点，event是个枚举值，具体的取值如下。 每个上报事件，都会有一些公共的字段会带回给开发者：

每个事件还有自己额外的一些字段，具体如下：

每个event的取值，对应的参数也不一样。

# 自定义返回按钮

注意，不可以在onBack回调函数里面调用wx.navigateBack等路由接口，可改为navigator组件或下面的路由跳转的接口进行跳转

PlayletManager.onBack(function() {
    // 在这里做一下挽留逻辑
    console.log('用户点击了返回按钮')
})

# 路由跳转

由于在插件页，小程序不能调用wx.navigateTo等接口，所以插件提供下面的接口进行跳转 注意：这些接口调用成功的前提是用户必须至少点击过页面。

PlayletManager.navigateTo(obj) // 含义和参数同wx.navigateTo
PlayletManager.navigateBack(obj) // 含义和参数同wx.navigateBack
PlayletManager.redirectTo(obj) // 含义和参数同wx.redirectTo
PlayletManager.switchTab(obj) // 含义和参数同wx.switchTab
PlayletManager.reLaunch(obj) // 含义和参数同wx.reLaunch

# 防录屏/截屏

若不调用此接口，播放器默认设置visualEffect为hidden具体使用可参考文档

PlayletManager.setVisualEffectOnCapture({
    visualEffect: 'hidden',
})

# 设置免费剧集列表

开发者可以进入页面就通过setCanPlaySerialList(freeList: [])接口设置免费剧列表（只针对已解锁剧集生效），如果开发者需要在用户观看过程中重新设置免费剧列表，可通过setFreeList设置，注意：此接口仅改变目录中的剧集显示状态，并不会做真正的解锁处理。

PlayletManager.setFreeList({
    list: [{start_serial_no: 1, end_serial_no: 10}], // 1~10集是免费剧集
})

# 设置用广告解锁剧集

开发者可以进入页面就通过setUseAdUnlock(list: [])接口设置需要广告解锁的剧集id，设置后，解锁按钮的文案变为“看广告解锁当前剧集”，点击后不会拉起充值弹窗，会回调给开发者事件。

注意：通过此接口设置的剧集，在选集界面上的 ui 表现会和免费剧集一样。

PlayletManager.setUseAdUnlock({
    list: [{start_serial_no: 79, end_serial_no: 80}], // 79~80集会通过广告解锁
})

开发者可通过接口onUseAdUnlock注册点击按钮的事件，通过激励视频去解锁

pm.onUseAdUnlock(function() {
    console.log('>>>USE_AD_UNLOCK')
    // 拉起激励视频广告去解锁
})

# 设置剧集未解锁时的视频预览

开发者可以设置剧集未解锁时的视频预览。当用户进入未解锁剧集时，可以在展示解锁按钮的同时在后台播放剧集视频预览：

// 播放预览
pm.startBackgroundPreview({
	loop: true, // 是否循环
	mask: true, // 是否遮罩
	muted: true, // 是否静音
})

// 停止预览播放
pm.stopBackgroundPreview()

注意：预览播放会消耗商家流量，请按需使用。

# 退出横屏

在用户进入横屏之后，如果碰到需要充值的剧集，需要退出横屏的，可调用此接口。接口调用如下：

pm.setPageOrientationPortrait()

# 播放原始视频

开发者可通过后台接口选择播放上传未经转码的原始视频。

接口url ： https://api.weixin.qq.com/wxadrama/setplayerdramarecmdswitch?access_token=

请求方法：POST

入参：json（不允许带注释）

{
    "entry_type":2002,
    "switch_status": true
}

# 最近观看组件

提供最近观看以供开发者在小程序中引用。在页面的 page.json 里面引入组件：

{
  "usingComponents": {
    "recent-list": "plugin://playlet-plugin/recent-list"
  }
}

recent-list即是最近观看组件，在页面 wxml 中添加组件：

<recent-list
    showHeader="{{true}}"
    bind:tapempty="onTapEmpty"
    bind:click="onClick"
    url="/pages/charge/charge"
></recent-list>

组件的使用和小程序组件类似，两个组件接收参数 url，url 表示列表为空的时候，点击“去看剧”跳转的链接，tapempty 事件表示点击了“去看剧”。

click 事件表示点击了对应的剧。

showHeader 属性表示是否显示组件的标题。

# 刷剧组件

提供刷剧组件以供开发者实现类似短剧广场等类似功能。在页面的 page.json 里引入组件：

{
  "usingComponents": {
    "drama-feed-list": "plugin://playlet-plugin/drama-feed-list"
  }
}

在页面wxml中添加组件：

<drama-feed-list
  id="drama-feed-list"
  autoplay
  bind:videoPlay="onVideoPlay"
  bind:videoPause="onVideoPause"
  bind:videoEnded="onVideoEnded"
  bind:videoError="onVideoError"
  bind:change="onChange"
  bind:watchFullDrama="onWatchFullDrama"
></drama-feed-list>

其中组件支持的参数如下：

组件支持的事件如下：

事件中的 detail 字段会带有下述参数：

如果需要控制刷剧组件的播放和暂停，可通过调用组件实例的方法实现：

this.selectComponent('#drama-feed-list').play()
this.selectComponent('#drama-feed-list').pause()

// 当 mode 为 custom-list 的时候，还支持以下接口
this.selectComponent('#drama-feed-list').appendCustomList([{ dramaId: '', srcAppid: '' }])
this.selectComponent('#drama-feed-list').replaceCustomList([{ dramaId: '', srcAppid: '' }])

使用刷剧组件有以下几点需要注意：

1. 目前刷剧组件播放的都是短剧的第一集。
2. 当前视频播放完后，刷剧组件并不会切到下一集/下一部短剧，而是自动重播当前视频。
3. 点击“看全集”按钮时触发的 watchFullDrama 事件需要开发者处理，一般可处理为跳转到该短剧的实际播放页。

刷剧组件本身有两种模式，一种是普通模式，一种是自定义刷剧模式。其中普通模式为开发者通过下述后台接口设置刷剧剧目，然后刷剧组件会从后台拉取推荐列表进行展示；而自定义刷剧模式则完全由开发者提供刷剧列表，刷剧组件只补全对应的信息再进行展示。

# 刷剧剧目设置接口

●功能：开发者可通过后台接口设置刷剧剧目

●接口url ： https://api.weixin.qq.com/wxadrama/developersetflushdrama?access_token=

请求方法：POST

入参：json(不允许带注释)

{
  "list": [
    {"src_appid":"example_src_appid", "drama_id":"123456", "drama_name":"example_drama_1"},
    {"src_appid":"example_src_appid", "drama_id":"123457", "drama_name":"example_drama_2"},
    {"src_appid":"example_src_appid", "drama_id":"123458", "drama_name":"example_drama_3"}
  ]
}

返回：json

{
  "errcode":0,
  "errmsg":"ok"
}

注1: 每次设置都会覆盖之前的设置，因此需要把所有想要接入刷剧组件的剧目一次加上；list不传或者传空数组，则将记录清空。

注2：所有src_appid，drama_id，drama_name都需要合法，不然会报错。另外，如果所传剧目没有授权给该调用账号的，也会失败报错。

注3：list当前的上限是1000个。

# 自定义刷剧模式

当组件属性 mode 传入 custom-list 字符串时表示切换到自定义刷剧模式，此时要求开发者必须传入 custom-list 属性：

<drama-feed-list
  id="drama-feed-list"
  mode="custom-list"
  custom-list="{{customList}}"
  autoplay
  bind:videoPlay="onVideoPlay"
  bind:videoPause="onVideoPause"
  bind:videoEnded="onVideoEnded"
  bind:videoError="onVideoError"
  bind:change="onChange"
  bind:watchFullDrama="onWatchFullDrama"
  bind:willReachEnd="onWillReachEnd"
  bind:reachEnd="onReachEnd"
></drama-feed-list>

其中 customList 的结构如下：

Component({
  data: {
    customList: [
      { dramaId: '', srcAppid: '' },
      { dramaId: '', srcAppid: '' },
      // ...
    ],
  },
})

因为短剧是通过 dramaId 和 srcAppid 来确定唯一一部剧，所以开发者只需要传入 dramaId 和 srcAppid 即可，刷剧组件会将这部剧的其余信息填补进去后进行展示。

当短剧列表即将被划动到底部时，刷剧组件会触发 willReachEnd 事件，开发者可在此事件中进行列表补充：

// 此处传入的列表会追加到现有的刷剧列表后面
this.selectComponent('#drama-feed-list').appendCustomList([
  { dramaId: '', srcAppid: '' },
  { dramaId: '', srcAppid: '' },
  // ...
])

注意：刷剧组件里会将列表中每 3 项计为一组，willReachEnd 事件目前会在划到倒数第二组的时候触发。建议传入的自定义列表至少为两组以上。

如果开发者想直接替换掉完整的刷剧列表，可以调用下述接口：

// 此处传入的列表会替换掉现有的刷剧列表
this.selectComponent('#drama-feed-list').replaceCustomList([
  { dramaId: '', srcAppid: '' },
  { dramaId: '', srcAppid: '' },
  // ...
])

# 运营能力

完成播放器插件基础接入流程后，可根据业务需求按需使用相关运营能力。

# 分享

# 分享开关

分享开关默认打开，您可以通过调用 PlayletManager 的 setDramaFlag 方法来打开或关闭分享开关。示例代码如下：

PlayletManager.setDramaFlag({
    share: true,
    withShareTicket: true
})

请注意，若小程序本身的分享能力受限，则分享入口则只有分享海报功能。withShareTicket为true可获取更多信息，具体使用可参考文档。

# 分享海报

播放器支持生成剧目海报。

开发者需要先在MP完成隐私协议配置，否则将隐藏C端用户的海报生成入口。

隐私协议配置

路径：设置-基本设置-服务内容声明-用户隐私保护指引

点击“更新”/“去完善”，选择“相册（仅写入）权限”

# 分享参数

您可以在 URL 中传入 extParam 参数，在分享时会将此参数带到分享出去的卡片上。有两种设置 extParam 的方式：

a. 在 navigateTo 跳转页面时，将此参数放到 URL 上。

b. 通过 PlayletManager.setExtParam(extParam)设置。注意，我们会对此参数进行 encodeURIComponent 编码，因此在获取此参数时，开发者需要进行 decodeURIComponent 解码操作后再解析。

# shareId

每次分享都会在分享出去的小程序卡片或者小程序码的 path 里面带参数 shareId，而且此 shareId 会通过 onDataReport 事件报给开发者，当用户再从卡片进入播放器，开发者可通过 getShareParams 方法获得此参数，进一步关联之前分享的用户，做一些分享相关的运营活动。

// 开启分享以及 withShareTicket
pm.setDramaFlag({
  share: true,
  withShareTicket: true
})

// 获取分享参数,页面栈只有短剧播放器一个页面的时候可获取到此参数
// 例如从分享卡片进入、从投流广告直接跳转到播放器页面，从二维码直接进入播放器页面等情况
playletPlugin.getShareParams().then(res => {
  console.log('getLaunch options query res', res)

  // 关于 extParam 的处理，需要先做 decodeURIComponent 之后才能得到原值
  const extParam = decodeURIComponent(res.extParam)
  console.log('getLaunch options extParam', extParam)
  
  // 如果设置了 withShareTicket 为true，可通过文档的方法获取更多信息
  // https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/share.html
  const enterOptions = wx.getEnterOptionsSync()
  console.log('getLaunch options shareTicket', enterOptions.shareTicket)
}).catch(err => {
  console.error('getLaunch options query err', err)
})

// 设置分享参数
pm.setExtParam('scene')

# 分享组件

从1.1.1版本开始支持分享组件组件，具体使用如下： 首先在page.json里面引用分享组件

{
    "usingComponents": {
        "playlet-share": "plugin://playlet-plugin/share"
    }
}

在页面wxml引入分享组件

<playlet-share
    playerId="{{playerId}}"
    imageUrl="{{imageUrl}}"
    title="{{title}}"
    shareExt="ext%3D1%26extb%3D2"
>
    <text style="font-size:18px;color:red;line-height:1em;">点击分享</text>
</playlet-share>

playerId是播放器页面的id，在onPlayerLoad的时候可获取，或者是getInfo接口会返回。 imageUrl是分享卡片的图片，title是分享卡片的标题，shareExt是分享的自定义参数，会带在小程序的页面路径上。

# 运营位

在胶囊旁边显示“活动”运营位，icon可自定义。 可通过PlayletManager的setActivityInfo(info)来进行设置，具体的示例代码可参考

pm.setActivityInfo({
  url: '', // 活动页面的路径，必填
  logo: '', // 显示的icon的url
})

# 自定义开放区域

为了最大程度提高播放器的灵活性，目前开放了一些区域让开发者自定义，可开放的的区域如下图所示：

注意：open-area-left-side 和 open-area-left 的区域是一样的，均如上图所述，其中 open-area-left-side 可设置多个实例，且可定义每个组件实例的宽高和位置。

具体接入类似充值弹窗的内容，首先在 app.json 内注册组件，如下所示

{
  "usingComponents": {
    "charge-dialog": "/components/charge-dialog/charge-dialog",
    "open-area-left": "/components/open-area-left/open-area-left",
    "open-area-left-side": "/components/open-area-left-side/open-area-left-side",
  },
  "plugins": {
    "playlet-plugin": {
      "version": "latest",
      "provider": "wx94a6522b1d640c3b",
      "genericsImplementation": {
        "playlet": {
          "charge-dialog": "/components/charge-dialog/charge-dialog",
          "open-area-left": "/components/open-area-left/open-area-left",
          "open-area-left-side": "/components/open-area-left-side/open-area-left-side",
        }
      }
    }
  }
}

open-area-left、open-area-left-side 是开发者需要实现的组件，当需要展示这几个组件的时候，可调用 PlayletManager 的 updateOpenArea 方法来显示/隐藏组件：

pm.updateOpenArea({
  showLeft: true, // 显示 open-area-left 组件
  leftWidth: 72, // 宽度，超出截断
  leftHeight: 100, // 高度，超出截断

  // 显示 open-area-left-side 组件
  leftsideAreaList: [{
    // left、top、width、height 定义每个元素的位置
    left: 10,
    top: 100,
    width: 400,
    height: 172,

    // 同时可以透传一些字段给组件内部
    xxx: '',
  }],
  ext: '', // 如果需要统一额外传一些数据给组件，可通过此参数传入
})

以下为组件的实现参考：

// open-area-left 组件
Component({
  properties: {
    playerId: {
      type: String,
      value: '',
    },
    serialNo: {
      type: Number,
      value: 0,
    },
    ext: {
      type: String,
      value: '',
    },
  },
})

// open-area-left-side 组件
Component({
  properties: {
    playerId: {
      type: String,
      value: ''
    },
    serialNo: {
      type: Number,
      value: 0
    },
    ext: {
      type: String,
      value: ''
    },
    item: { // 对应的 leftsideAreaList 数组中的某一项
      type: Object,
      value: {},
    },
    index: { // 对应的 leftsideAreaList 数组中的下标
      type: Number,
      value: 0,
    },
  },
})

# 公众号联动

详情可见能力介绍

# 推荐位

播放器插件在不同场景提供推荐位以供开发者使用，推荐位默认关闭，可通过推荐位控制接口打开推荐位。

注意：推荐剧库大于等于 6 部时，才会在相应场景中出现推荐位。

# 推荐位控制接口

●功能：开发者可通过后台接口控制推荐位的开启与关闭。

●接口url ： https://api.weixin.qq.com/wxadrama/setplayerdramarecmdswitch?access_token=

请求方法：POST

入参：json(不允许带注释)

{
    "entry_type":1,
    "switch_status": true
}

返回：json

{
    "errcode":0,
    "errmsg":"ok"
}

# 推荐剧目设置

开启推荐位之后，推荐剧目范围默认为播放小程序所有已授权的剧目。

同时支持开发者设置推荐库，在设置推荐库之后，推荐剧目将从开发者设置的推荐剧目中产生。

●接口url ： https://api.weixin.qq.com/wxadrama/developersetrecmddrama?access_token=xxxxxx

{

    "entry_type":1, //1-剧结束 2-选集最右侧推荐 3-剧集profile页相关推荐

    "src_appid":"wx94a6522b1d640c3b",

    "drama_id":"666666",

    "list":[

        {"src_appid":"wx4f3ca6d4c2407ccc","drama_id":"266946"},

        {"src_appid":"wx5cefe18a7902141d","drama_id":"236424"}

    ]

}

注1：src_appid 和 drama_id 同时为空，代表小程序维度。展示优先级低于剧粒度的设置。

注2: 每次设置都会覆盖之前的设置，需要把所有要设置的推荐剧一次加上；list不传或者传空数组，则将记录清空。

注3：所有appid需要合法，不然报错。另外存在所传剧目没有授权给该调用账号的，也会失败报错。

注4：list当前的上限是200个。

# 短剧上架

# 短剧上架设置接口

●功能：开发者可通过后台接口设置小程序内短剧的上架时间。在短剧提审成功并授权后默认直接上架，如需设置特定上架时间可以调用该接口。

●接口url ： https://api.weixin.qq.com/wxadrama/developerpublishdrama?access_token=

请求方法：POST

入参：json(不允许带注释)

{
   "list": [
           {"src_appid":"example_src_appid", "drama_id":"123456", "drama_name":"example_drama_1", "publish_time":1734624000},
           {"src_appid":"example_src_appid", "drama_id":"123457", "drama_name":"example_drama_2", "publish_time":1734600000},
           {"src_appid":"example_src_appid", "drama_id":"123458", "drama_name":"example_drama_3", "publish_time":1730000030}}
     ]
}

返回：json

{
    "errcode":0,
    "errmsg":"ok"
}

注1：所有src_appid，drama_id，drama_name 都需要合法和已授权。

注2：publish_time为秒级时间戳，表示从"1970-01-01 00:00:00"开始到当前时间的总秒数。publish_time可以被多次设置，且平台取用最新的publish_time。

# 获取已上架短剧

●功能：开发者可以通过该接口查询通过“短剧上架设置接口”设置上架的短剧。

●接口url ： https://api.weixin.qq.com/wxadrama/developergetpublisheddrama?access_token=

请求方法：POST

返回：json

{
    "list":[
        {"src_appid":"example_appid","drama_id":"example_drama_id_1","publish_time":1744626100},
        {"src_appid":"example_appid","drama_id":"example_drama_id_2","publish_time":1744626200},
    ]
    "errcode":0,
    "errmsg":"ok"
}

# 短剧变现类型

# 设置短剧变现类型

●功能：在视频号推荐、视频号入口展示、播放器选集等场景，对IAA/IAP/IAAP有不同的精准策略。若不进行配置/配置出错，将影响你的营收和流量分配。

●接口url ： https://api.weixin.qq.com/wxadrama/developersetiaadrama?access_token=

请求方法：POST

入参：json(不允许带注释)

{
   "list": [
           {"src_appid":"example_src_appid", "drama_id":"123456", "iaa_type": 1, "vip_flag":1 },
           {"src_appid":"example_src_appid", "drama_id":"123457", "iaa_type": 2, "vip_flag":1 },
           {"src_appid":"example_src_appid", "drama_id":"123458", "iaa_type": 1, "vip_flag":1 }
     ]
}

返回：json

{
    "errcode":0,
    "errmsg":"ok"
}

注1：平台以 src_appid x drama_id 唯一标识一部短剧。 注2：access_token会被平台校验并映射成当前小程序的appid，接口调用后将以appid x src_appid x drama_id 粒度对当前小程序下的一部短剧进行设置。

# 获取短剧变现类型

●功能：获取已设置短剧的变现类型。

●接口url ： https://api.weixin.qq.com/wxadrama/developergetiaadrama?access_token=

请求方法：POST

入参：json(不允许带注释)

{
   "list": [
           {"src_appid":"example_src_appid", "drama_id":"123456"},
           {"src_appid":"example_src_appid", "drama_id":"123457"}
     ]
}

返回：json

{
   "list": [
           {"src_appid":"example_src_appid", "drama_id":"123456", "iaa_type": 1, "vip_flag":1 },
           {"src_appid":"example_src_appid", "drama_id":"123457", "iaa_type": 2, "vip_flag":1 }
     ],
    "errcode":0,
    "errmsg":"ok"
}

# 批处理短剧合作推广计划

●功能： 使用接口设置后，可批量将剧目加入/退出短剧推广计划中。 注： 1、剧目加入计划后，会用于生态内的分发，如小程序-发现页、公众号推荐等场景。 2、该接口必须由剧目提审时的小程序调用，即access_token对应的小程序appid必须等于src_appid。 3、每次批量加入短剧最大数目限制为100。

●接口url ： https://api.weixin.qq.com/wxadrama/batchprocessdramapromotion?access_token=

请求方法：POST

入参：json(不允许带注释)

返回：json

加入/退出计划请求示例

此处仅以加入计划为例，如需退出计划可修改action_type为3。

{
   "action_type": 1,
   "list": [
           {"src_appid":"example_src_appid", "drama_id":"123456"},
           {"src_appid":"example_src_appid", "drama_id":"123457"}
     ]
}

加入/退出计划返回示例

{
    "errcode":0,
    "errmsg":"ok"
}

查询计划请求示例

{
   "action_type": 2,
   "list": [
           {"src_appid":"example_src_appid", "drama_id":"123456"},
           {"src_appid":"example_src_appid", "drama_id":"123457"}
     ]
}

查询计划返回示例

{
   "list": [
           {"src_appid":"example_src_appid", "drama_id":"123456", "status": 0 },
           {"src_appid":"example_src_appid", "drama_id":"123457", "status": 1 }
     ],
    "errcode":0,
    "errmsg":"ok"
}

# 获取短剧合作推广活动

●功能： 该接口可获取当前小程序短剧所关联的短剧合作推广活动。 注： 1、批量获取小程序提交审核的所有关联小程序短剧的推广活动 2、批量获取小程序可播放短剧的推广活动，无法获取该短剧其他可播放小程序的推广活动 3、传入event_id_list用于筛选指定event_id的推广活动，最大数量限制为50

●接口url ： https://api.weixin.qq.com/wxadrama/getfinderevent?access_token=

请求方法：POST

入参：json(不允许带注释)

返回：json

请求示例

{
   "event_id_list": [] //为空时全量读取
}

返回示例

{
    "finder_event_list": [
        {
            "encrypted_event_id": "event/id",
            "event_name": "《示例短剧》示例小程序",
            "event_url": "https://channels.weixin.qq.com/mobile/toNativeActivity.html?title=&topicType=&eventEncryptedTopicId=&authorNickname=",
            "src_appid": "wx",
            "drama_id": "10000"
        }
    ],
    "errcode": 0,
    "errmsg": "ok"
}

# 常见问题

# 基础库兼容问题

播放器功能支持基础库版本为2.21.4及以上

# 测试注意

●多种进入播放器的场景测试：开发者需要测试不同的场景，例如从首页跳转（navigateTo/redirectTo）、从分享卡片进入，以及从其他小程序通过 navigateToMiniProgram 跳转等情况。确保在各种场景下播放器功能正常运行。

●关于 lazyCodeLoading 的注意事项：如果开启了 lazyCodeLoading 功能，需要注意在开发者工具中进行调试时可能会遇到 bug。在开发者工具中，需要先关闭以下设置：

{
    "lazyCodeLoading":"requiredComponents"
}

# 投放路径设置

# 投放的页面路径

plugin-private://wx94a6522b1d640c3b/pages/playlet/playlet?dramaId={dramaId}&srcAppid={srcAppid}&extParam={extParam}

其中{dramaId}表示剧集id，{srcAppid}提审方appid，请替换成对应的参数，{extParam}是分享参数，具体见分享章节介绍

# 存量投放链接处理

若之前投放的链接是pages/player/index，可使用redirectTo跳转到播放器的页面链接 （即plugin-private://wx94a6522b1d640c3b/pages/playlet/playlet开头的链接），用户在播放器页面点击左上角后，可返回首页。

# 版本更新日志

查看更新日志

# 附录

# 完整接口文档

查看完整接口文档

# 播放器后台返回码

# 接入咨询

短剧贴片申请

问卷填写

播放器接入问题可加群咨询微信团队