# 介绍

小说阅读器是微信官方为小说类目小程序提供的阅读器插件。

为保障平台小说小程序规范运营和用户的阅读及使用体验,符合小说类判定的小程序,需申请【文娱-小说】类目,并统一使用官方阅读组件进行内容投放。

# 效果示例

image.png image.png image.png image.png

# 代码示例

代码片段示例

# 接入流程

# 添加插件

小说类目小程序默认开通插件权限。

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

{
  "plugins": {
    "novel-plugin": {
      "version": "latest",
      "provider": "wx293c4b6097a8a4d0"
    }
  }
}

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

# 插件初始化

插件页与小程序之间是通过事件来进行通信的,这就意味着小程序需要编写相应的订阅事件和发布事件逻辑。

在插件页初始化完毕后,会发送一个事件告知给小程序,插件页初始化完毕,小程序端需要订阅这个事件,示例代码如下:

// app.js
// 引入阅读器插件
// 详见https://developers.weixin.qq.com/miniprogram/dev/reference/api/requirePlugin.html
const novelPlugin = requirePlugin('novel-plugin')

App({
  onLaunch() {
    // 监听进入插件页事件
    novelPlugin.onPageLoad(onNovelPluginLoad)
  },
})

function onNovelPluginLoad(data) {
  // data.id - 阅读器实例 id,每个插件页对应一个阅读器实例
  const novelManager = novelPlugin.getNovelManager(data.id)
  
  // getId() 返回当前阅读器实例 id
  console.log('id:', novelManager.getId())

  // 设置目录状态
  novelManager.setContents({
    contents: [
      {
        index: 0, // 第一章
        status: 0, // 免费
      },
      {
        index: 1, // 第二章
        status: 2, // 未解锁
      },
      {
        index: 2, // 第三章
        status: 1, // 已解锁
      },
      // ...
    ],
  })

  // 监听用户行为事件
  novelManager.onUserTriggerEvent(res => {
    console.log('onUserTriggerEvent', res.event_id, res)
  })
}

注意:

  1. 该逻辑建议放在 app.js 中,确保用户直接进入阅读器插件页时也能正确处理。
  2. onPageLoad 需要传入一个回调函数来接受从插件传入的值。
  3. onPageLoad 在进入插件页后才会触发。

# 跳转插件页

插件页的路径为 plugin-private://wx293c4b6097a8a4d0/pages/novel/index?bookId=xxx,该路径可以当成普通页面路径进行使用,通过 navigateTo 或 redirectTo 等方法进行跳转。

wx.redirectTo({
  url: 'plugin-private://wx293c4b6097a8a4d0/pages/novel/index?bookId=xxx'
})

支持参数:

参数 必填 描述
bookId 书籍 id
customServerParams 透传到服务器的参数,因为是在 path 上,所以如果含有特殊字符,需自行 encode,防止解析出错
chapterIndex 跳转章节下标(从 0 开始)
paragraphIndex 跳转段落下标,默认 0(从 0 开始)
fontSize 指定默认字体大小(0 - 9 从小到大)
turnPageWay 默认翻页方式:TURN_PAGE_WAY_SWIPE - 覆盖翻页;TURN_PAGE_WAY_MOVE - 平移翻页;TURN_PAGE_WAY_SCROLL - 上下翻页
blockUnpaidScroll 传入值为 1 时,滑动到未解锁章节会阻塞住,用户无法往下滑动;传入值为 0 时则不做阻塞;默认值为 1
disableAutoShowChargeDialog 传入值为 0 时,进入未解锁章节时会自动拉起付费弹窗;传入值为 1 时则关闭此特性;默认值为 0

注意:

  1. bookId 是书籍 id,创建作品后会返回,详情可参考小说作品管理接口文档
  2. chapterIndex 和 paragraphIndex 用于强制跳转到指定章节和段落;用户的阅读进度由阅读器自行保存,无需接入方维护。
  3. fontSize 参数用于修改默认字体大小,若用户已经设置过字体大小,则该参数无效。turnPageWay 参数同理。

# 章节解锁组件

在未解锁章节末尾默认会有一个按钮,点击按钮后会拉起半屏,半屏中即是需要用户传入自定义组件的抽象节点

iOS 中默认是显示一段提示而非按钮,可通过 setChargeWay 接口让按钮显示

image.png

首先需要编写一个自定义组件 charge-dialog,该组件和普通自定义组件编写规则一致:

<!-- charge-dialog.wxml,以下代码仅供参考 -->
<button bind:tap="unlock">解锁第 {{ chapterIndex + 1 }} 章</button>
// charge-dialog.js,以下代码仅供参考
const novelPlugin = requirePlugin('novel-plugin')

Component({
  properties: {
    novelManagerId: {
      type: Number,
      value: -1,
    },
    bookId: {
      type: String,
      value: '',
    },
    chapterIndex: {
      type: Number,
      value: -1,
    },
    chapterId: {
      type: String,
      value: '',
    },
    originalId: {
      type: String,
      value: '',
    },
  },

  methods: {
    unlock() {
      // 取出对应的阅读器实例
      const novelManager = novelPlugin.getNovelManager(this.properties.novelManagerId)

      // do something

      // 告诉阅读器这一章已解锁
      novelManager.paymentCompleted()
    },
  },
})

然后在 app.json 中将此组件作为抽象节点添加到插件设置中:

{
  "plugins": {
    "novel-plugin": {
      "version": "latest",
      "provider": "wx293c4b6097a8a4d0",
      "genericsImplementation": {
        "novel": {
          "charge-dialog": "path/to/component"
        }
      }
    }
  }
}

阅读器插件会传入以下属性给该组件:

参数 类型 描述
novelManagerId Number 阅读器实例 id
bookId String 书籍 id
chapterIndex Number 章节下标
chapterId String 章节 id
originalId String 该属性是否传入取决于接入方是否上传该属性

注意:

  1. 解锁流程结束后,应调用 paymentCompleted 接口通知阅读器解锁完成,以确保页面能够正确更新。
  2. 抽象节点一般是为阅读器插件准备,小程序本身不会直接引用它们。在某些构建环境下,由于组件未被使用,可能会被编译工具进行优化,导致阅读器无法找到插件。如果遇到这种情况,请检查编译产物,确保组件代码存在。如果组件代码不存在,可以在某个页面中引用该组件(即使不使用),以确保组件不会被优化掉。
  3. 可以使用 setChargeWay 接口来自定义收费组件的文案和行为,以满足特定的业务需求。
  4. 可以使用 openChargeDialog、closeChargeDialog 接口来主动打开/关闭章节解锁组件。
  5. 解锁组件最大高度是屏幕高度的 75%,若有较长内容时,开发者应使用 scroll-view 组件。

# 接口列表

# novelPlugin

阅读器插件,通过 requirePlugin 引入。

const novelPlugin = requirePlugin('novel-plugin')

# novelPlugin.onPageLoad(Function callback)

当用户进入阅读器插件页时便会触发此事件。

事件监听回调函数参数如下:

参数 类型 描述
id Number 当前插件页对应的阅读器实例 id
const novelPlugin = requirePlugin('novel-plugin')

novelPlugin.onPageLoad(params => {
  // do something
})

# NovelManager novelPlugin.getNovelManager(Number id)

获取阅读器实例,通过此实例可对该插件页进行操作管理。

传入的参数 id 为当前插件页对应的阅读器实例 id,可在 onPageLoad 中获取。

const novelPlugin = requirePlugin('novel-plugin')

const novelManager = novelPlugin.getNovelManager(id)

# novelPlugin.getCurrentNovelManager()

获取当前页的阅读器实例。如果当前页非正常可用的插件页,则不会返回。

通过此接口亦可判断当前页是否阅读器插件页。

const novelPlugin = requirePlugin('novel-plugin')

const novelManager = novelPlugin.getCurrentNovelManager()

# novelPlugin.setLoggerConfig(Object params)

设置插件日志显示级别,默认只显示 warn 和 error。

params 参数结构如下:

参数 类型 必填 描述
info Boolean 是否输出 info 日志,默认为 false
debug Boolean 是否输出 debug 日志,默认为 false
log Boolean 是否输出 log 日志,默认为 false
warn Boolean 是否输出 warn 日志,默认为 true
error Boolean 是否输出 error 日志,默认为 true
const novelPlugin = requirePlugin('novel-plugin')

novelPlugin.setLoggerConfig({
  info: true,
  debug: true,
  log: true,
  warn: true,
  error: true,
})

# NovelManager

阅读器,用于对插件页进行操作管理。每个插件页对应一个阅读器实例。

const novelPlugin = requirePlugin('novel-plugin')

novelPlugin.onPageLoad(params => {
  // 获取阅读器实例
  const novelManager = novelPlugin.getNovelManager(params.id)

  // do something
})

# Number NovelManager.getId()

获取阅读器实例 id。

const novelManagerId = novelManager.getId()

# String NovelManager.getBookId()

获取阅读器实例对应的书籍 id。

const bookId = novelManager.getBookId()

# Object NovelManager.getPluginInfo()

获取阅读器信息。

返回参数结构如下:

参数 类型 描述
pluginAppid String 插件 appId
pluginVersion String 插件版本号
query Object 插件页的 query 参数对象

注意:若是从书籍分享卡片或是其他方式直接进入到插件页,开发者便可通过此接口的 query 字段获取到插件页 path 上的参数。

const pluginInfo = novelManager.getPluginInfo()

# Object NovelManager.getLaunchOptions()

获取启动参数,与 wx.getLaunchOptionsSync 返回值一致。

const launchOptions = NovelManager.getLaunchOptions()

# NovelManager.onPluginError(Function callback)

监听阅读器主动抛出的错误。

事件监听回调函数参数如下:

参数 类型 描述
event String 错误类型
novelManager.onPluginError(res => {
  // do something
})

# String NovelManager.getCustomServerParams()

获取 customServerParams 参数,含义同跳转插件页时传入的 customServerParams 参数。

const customServerParams = novelManager.getCustomServerParams()

# NovelManager.setCustomServerParams(Object params)

设置 customServerParams 参数,含义同跳转插件页时传入的 customServerParams 参数。

params 参数结构如下:

参数 类型 必填 描述
customServerParams String
novelManager.setCustomServerParams({
  customServerParams: 'xxx'
})

# NovelManager.setClosePluginInfo(Object params)

设置用户点击书籍介绍页导航栏返回按钮时的跳转行为,在页面栈中只有当前插件页时生效。如果当前页面栈中页面数量大于 1,则会走 navigateBack 逻辑返回上一个页面。

params 参数结构如下:

参数 类型 必填 描述
url String 跳转的路径,如不传则默认 reLaunch 到小程序首页
mode String 跳转方式,支持 switchTab 或 redirectTo,取决于要跳转的目标页面类型;默认值为 redirectTo
novelManager.setClosePluginInfo({
  url: '/pages/tab/index',
  mode: 'switchTab',
})

# NovelManager.setShareParams(Object params)

设置分享书籍时的参数。

params 参数结构如下:

参数 类型 必填 描述
enable Boolean 是否开启分享能力,默认为 true
title String 书籍标题
imageUrl String 书籍封面
args Object 在分享时可携带的参数,要求 key 和 value 均为 String 类型
// 关闭分享
novelManager.setShareParams({
  enable: false,
})

// 调整分享参数
novelManager.setShareParams({
  title: 'xxx',
  imageUrl: 'xxx',
  args: {
    a: '123',
    b: '321',
  },
})

# NovelManager.setBookshelfStatus(Object params)

设置书架状态。此状态阅读器不会做任何存储,需要开发者传入。

params 参数结构如下:

参数 类型 必填 描述
bookshelfStatus Number 当前书架状态:0 - 未添加;1 - 已添加
showToast Boolean 是否在非第一次书架状态变更时展示提示,默认为 true
novelManager.setBookshelfStatus({
  bookshelfStatus: 1,
})

# NovelManager.onClickBookshelf(Function callback)

监听书架按钮点击事件。此事件触发时不会改变当前书架状态,需要等用户处理完事件后手动调用 setBookshelfStatus 来更新书架状态。

事件监听回调函数参数如下:

参数 类型 描述
bookshelfStatus Number 预期书架状态:0 - 未添加;1 - 已添加
novelManager.onClickBookshelf(res => {
  // do something

  // 用户处理好状态变更后,再手动更新书架状态
  novelManager.setBookshelfStatus({
    bookshelfStatus: !!res.bookshelfStatus ? 1 : 0,
  })
})

# NovelManager.setActivity(Object params)

设置“活动”按钮运营位。

image.png

params 参数结构如下:

参数 类型 必填 描述
url String 点击“活动”按钮后的跳转路径
novelManager.setActivity({
  url: '/pages/activity/index',
})

# NovelManager.setContents(Object params)

设置目录。

此方法只会更新目录的 ui,并不会实际进行章节的解锁操作,阅读器只有拉取到章节数据后才知道该章节是否解锁,无法知悉所有章节的解锁状态。如果开发者需要在目录上展示正确的解锁状态,便可使用此接口对章节进行一次解锁状态初始化。

章节如何解锁可参考文档中下一个部分的解锁链路。目录中的章节状态会优先以该链路中后台返回的解锁状态为准,其次再取此接口中设置的状态进行显示。

注意:如果通过此接口设置了某章节为已解锁状态,但是进入该章节(或该章节的临近章节)后发现目录变成了未解锁状态,这种情况一般是拉取到了章节数据后发现后台返回的状态是未解锁,便会以此状态为优先来更新目录。遇到此问题可先检查下开发者前端知悉的章节状态和开发者后台存储的章节状态是否没有对齐。

params 参数结构如下:

参数 类型 必填 描述
contents Array<Content> 章节解锁状态列表

Content 参数结构如下:

参数 类型 必填 描述
index Number 章节下标
status Number 章节解锁状态:0 - 免费章节;1 - 已解锁章节;2 - 未解锁章节
novelManager.setContents({
  contents: [
    {
      index: 0, // 第一章
      status: 0,
    },
    {
      index: 1, // 第二章
      status: 2,
    },
    {
      index: 2, // 第三章
      status: 1,
    },
  ],
})

# NovelManager.setChargeWay(Object params)

设置章节解锁方式。

params 参数结构如下:

参数 类型 必填 描述
globalConfig SetChargeWayItem 针对所有章节的全局设置
chapterConfigs Array<SetChargeWayItem> 按章节设置

SetChargeWayItem 参数结构如下:

参数 类型 必填 描述
mode Number 解锁方式:1 - 默认值,用户点击按钮会自动拉起章节解锁组件;2 - 用于广告解锁,用户点击按钮后触发 onUserClickAdUnlock 事件;3 - 用于自定义解锁,用户点击按钮后触发 onUserClickCustomUnlock 事件;4 - 不展示解锁按钮和提示信息
buttonText String 未解锁时显示的按钮文案,最多两个字
tip String 未解锁时显示的提示信息,最多 18 个字
showButton Boolean 是否展示解锁按钮,默认非 iOS 侧为 true,iOS 侧为 false。即 iOS 侧默认只展示提示信息不展示解锁按钮
chapterIndex Number 章节下标,globalConfig 中不用传该参数

注意:解锁按钮和提示信息的展示是互斥的,两者只能展示其一。

novelManager.setChargeWay({
  globalConfig: {
    mode: 2,
    buttonText: '解锁',
    tip: '暂不支持继续阅读',
  },
  chapterConfigs: [
    {
      chapterIndex: 19, // 第二十章
      mode: 1,
      buttonText: '购买',
      tip: 'xxx之后可继续阅读',
    },
  ]
})

# NovelManager.paymentCompleted(Object params)

通知阅读器解锁成功,阅读器会刷新当前章节状态。

params 参数结构如下:

参数 类型 必填 描述
chapterIndex Number 解锁完成的章节下标。如果是在章节解锁组件拉起时调用 paymentCompleted,则无需传入此字段,会默认取该章节解锁组件对应的章节下标来处理
novelManager.paymentCompleted()

# NovelManager.openChargeDialog(Object params)

拉起章节解锁组件。

params 参数结构如下:

参数 类型 必填 描述
chapterIndex Number 章节下标
chapterId String 章节 id
originalId String 章节原始 id,即开发者上传章节时传入的 original_id

注意:chapterIndex、chapterId、originalId 传入一个即可,若都不传入则拉起当前章节的章节解锁组件。

novelManager.openChargeDialog({
  chapterIndex: 10, // 第十一章
})

# NovelManager.closeChargeDialog()

关闭章节解锁组件。

novelManager.closeChargeDialog()

# NovelManager.onUserClickAdUnlock(Function callback)

当调用 setChargeWay 将章节解锁方式 mode 设置为 2 时,点击解锁按钮会触发此事件。

事件监听回调函数参数如下:

参数 类型 描述
chapterIndex Number 章节下标
novelManager.onUserClickAdUnlock(res => {
  // do something
})

# NovelManager.onUserClickCustomUnlock(Function callback)

当调用 setChargeWay 将章节解锁方式 mode 设置为 3 时,点击解锁按钮会触发此事件。

事件监听回调函数参数如下:

参数 类型 描述
chapterIndex Number 章节下标
novelManager.onUserClickCustomUnlock(res => {
  // do something
})

# NovelManager.onUserTriggerEvent(Function callback)

监听用户行为事件。目前支持的事件如下:

事件 id 触发时机
start_read 开始阅读书籍时
leave_readpage 用户离开阅读页时
read_error 内容发生报错时
change_chapter 切换章节时
change_page 翻页时
open_menu 唤起一级菜单时
close_menu 轻触收起一级菜单时
open_content 唤起目录页时
close_content 收起目录页时
open_setting 唤起设置面板
close_setting 收起设置面板
expose_introduction 书籍介绍页曝光
click_addbookshelf 点击“加入书架”
click_startread 点击“开始阅读”
leave_introduction 离开当前页
get_chapter 拉取章节数据结束
page_show 插件页 onShow 生命周期
page_hide 插件页 onHide 生命周期
page_unload 插件页 onUnload 生命周期

注意:插件页创建时的 page_show 事件开发者无法监听到,因为 onPageLoad 的触发时间会晚于插件页创建时的 onShow 生命周期

事件基础参数如下:

参数 类型 描述
event_id String 事件 id
appid String 小程序 appId
appstate String 小程序版本:0 - 正式版;1 - 体验版;2 - 开发版
book_id String 书籍 id
title String 书籍名
chapter_index Number 章节下标
chapter_title String 章节标题,change_chapter 事件触发后才会返回
first_category_id Number 一级类目 id
first_category_name String 一级类目名称
second_category_id Number 二级类目 id
second_category_name String 二级类目名称
third_category_id Number 三级类目 id
third_category_name String 三级类目名称
total_count Number 总字数
total_count_chapter Number 总章节数
complete_status_name String 完结状态
font_index Number 字体分级
background_index Number 背景样式
flip_mode Number 翻页方式:TURN_PAGE_WAY_SWIPE - 覆盖翻页;TURN_PAGE_WAY_MOVE - 平移翻页;TURN_PAGE_WAY_SCROLL - 上下翻页

另有部分参数只在特定事件下支持:

参数 类型 描述 支持该参数的事件 id
delay_time Number 加载时间 start_read
pay_status Number 章节状态:0 - 免费章节;1 - 已解锁;2 - 未解锁 start_read、get_chapter
read_time Number 阅读时长 leave_readpage、change_chapter、change_page
type Number 离开方式:1 - 退出页面;2 - 退后台 leave_introduction、leave_readpage
error String 错误描述 read_error
error_type Number 错误码 read_error
slide_type Number 切换方式:1 - 滑动;2 - 选集 change_chapter
intro String 书本简介 expose_introduction
novelManager.onUserTriggerEvent(res => {
  console.log('onUserTriggerEvent', res.event_id, res)
})

# NovelManager.onCustomEvent(String name, Function callback)

监听开发者自定义事件。

novelManager.onCustomEvent('customEvent', res => {
  // do something
})

# NovelManager.emitCustomEvent(String name, Object params)

触发开发者自定义事件。

novelManager.emitCustomEvent('customEvent', {
  a: '123',
  b: 321,
})

# NovelManager.setParagraphBlock(Object params)

在正文中插入自定义段落。

image.png

和章节解锁组件一样,需要先编写一个自定义组件 paragraph-block,该组件和普通自定义组件编写规则一致,然后在 app.json 中将此组件作为抽象节点添加到插件设置中:

{
  "plugins": {
    "novel-plugin": {
      "version": "latest",
      "provider": "wx293c4b6097a8a4d0",
      "genericsImplementation": {
        "novel": {
          "charge-dialog": "path/to/component",
          "paragraph-block": "path/to/component2",
        }
      }
    }
  }
}

阅读器插件会传入以下属性给该组件:

参数 类型 描述
novelManagerId Number 阅读器实例 id
chapterIndex Number 章节下标
ext String 透传参数

然后再调用此接口可以将 paragraph-block 作为自定义段落插入到文中,params 参数结构如下:

参数 类型 必填 描述
globalConfigs Array<ParagraphBlock> 针对所有章节的全局设置
chapterConfigs Array<ChapterParagraphBlock> 按章节设置

ChapterParagraphBlock 参数结构如下:

参数 类型 必填 描述
chapterIndex Number 章节下标
blocks Array<ParagraphBlock> 自定义段落设置

ParagraphBlock 参数结构如下:

参数 类型 必填 描述
height Number 自定义段落高度,单位 px
position Number 自定义段落位置,0 表示在标题前,1 表示在第一段文字前,以此类推
ext String 透传给自定义组件的参数
key String 自定义段落唯一 id,用于阅读器内部的 wx:for 列表更新;若不传则阅读器会自动生成一个
disableContinueReading Boolean 若为 true,则用户在阅读到此段落时无法阅读当前章节内该段落之后的内容;默认为 false
fillContentBefore Boolean 若为 true,则当前页空间不足以容纳该段落时,会先将后面段落内容尽可能地填充到当前页,然后在下一页进行该段落的插入;默认为 false
onlyRenderInCurrentPage Boolean 若为 true,则在平移翻页/覆盖翻页时,此自定义段落只会在当前页进入动画结束后渲染;默认为 false,即在过渡页中也会进行渲染,以优化用户的切页体验

使用此接口时有以下要点必须注意:

  1. 自定义段落的高度是必须传入的,阅读器的分页计算需要明确知道每个段落的高度。
  2. 此接口每次调用都会触发重新排版和渲染,会对性能和体验有一定影响,请勿频繁调用该方法。
  3. 每章最多只能插入十个自定义段落。
  4. 全局设置会和按章节设置混在一起进行展示。
novelManager.setParagraphBlock({
  globalConfigs: [ // 在这里设置的是全局设置 会在所有章节生效
    {
      height: 300,
      position: 1,
      ext: 'global',
    },
  ],
  chapterConfigs: [
    {
      chapterIndex: 0, // 第一章
      blocks: [
        {
          height: 100,
          position: 1,
          ext: 'chapter',
        }
      ],
    },
  ]
})

# NovelManager.setAdBlock(Object params)

在正文中插入广告段落。

params 参数结构如下:

参数 类型 必填 描述
chapterConfigs Array<ChapterAdBlock> 按章节设置

ChapterAdBlock 参数结构如下:

参数 类型 必填 描述
chapterIndex Number 章节下标
blocks Array<AdBlock> 自定义段落设置

AdBlock 参数结构如下:

参数 类型 必填 描述
type Number 广告类型:1 - 强制观看广告;默认值为 1
position Number 广告段落位置,0 表示在标题前,1 表示在第一段文字前,以此类推。此位置并不一定精确的位置,如强制观看广告类型,会将广告前一页面进行填充(如自定义段落的 fillContentBefore 设置),相当于会将广告段落按一定程度往后挪动
duration Number 强制观看广告要求强制观看的时长,单位为秒,范围为 0 - 30,默认值为 6
unitId String 原生模板广告的广告单元 id,参考 ad-custom 组件文档

目前广告段落只支持一种广告:

广告类型 描述
强制观看广告 默认占用一页的高度,用户需要观看广告足够时间后才能向后翻页/滚动,只有广告出现在页面中时才会开始计时。若用户观看广告符合条件后,记录会保存在本地,在一定时间内该广告都将不再要求强制观看时间

注意:广告以 {bookId}-{chapterId}-{position}-{type} 组合为唯一 id,此 id 不同即视为不同广告。

novelManager.setAdBlock({
  chapterConfigs: [
    {
      chapterIndex: 0, // 第一章
      blocks: [
        {
          position: 10,
          duration: 10,
          unitId: 'adunit-xxxxxxxxx',
        },
      ],
    },
  ],
})

# NovelManager.setFullScreenComponentStatus(Object params)

插入全屏组件。

注意:全屏组件会直接渲染在阅读器之上,会对用户阅读体验有影响,且会截获用户的点击等事件,请谨慎使用。

image.png

和章节解锁组件一样,需要先编写一个自定义组件 full-screen,该组件和普通自定义组件编写规则一致,然后在 app.json 中将此组件作为抽象节点添加到插件设置中:

{
  "plugins": {
    "novel-plugin": {
      "version": "latest",
      "provider": "wx293c4b6097a8a4d0",
      "genericsImplementation": {
        "novel": {
          "charge-dialog": "path/to/component",
          "full-screen": "path/to/component2",
        }
      }
    }
  }
}

阅读器插件会传入以下属性给该组件:

参数 类型 描述
novelManagerId Number 阅读器实例 id
chapterIndex Number 章节下标

然后再调用此接口可以将 full-screen 渲染在阅读器之上,params 参数结构如下:

参数 类型 必填 描述
show Boolean 展示或销毁全屏组件
novelManager.setFullScreenComponentStatus({
  show: true,
})

# NovelManager.navigateToMiniProgram(Object params)

接口含义和参数同 wx.navigateToMiniProgram。

# NovelManager.reLaunch(Object params)

接口含义和参数同 wx.reLaunch。

# NovelManager.switchTab(Object params)

接口含义和参数同 wx.switchTab。

# NovelManager.redirectTo(Object params)

接口含义和参数同 wx.redirectTo。

# NovelManager.navigateTo(Object params)

接口含义和参数同 wx.navigateTo。

# 章节解锁链路

image.png image.png

# 消息推送

微信和开发者之间是通过消息推送来传递章节解锁信息,故需要开发者开通消息推送。

  1. 开发者服务器接收消息推送 - 支持
  2. 云函数接收消息推送 - 支持
  3. 微信云托管服务接收消息推送 - 支持
  4. 第三方服务器接收消息推送 (小说权限集授权给第三方)- 支持

注意:这里消息推送超时时间为4s(常规消息推送是5s)。

# 消息格式

# 接收的数据格式

参数 类型 说明
ToUserName String 小程序原始 id
FromUserName String 用户 openid
CreateTime Number 消息发送时间
MsgType String 固定值:event
Event String 固定值:wxa_novel_chapter_permission
BookId String 作品 id
ChapterIndex Number 章节编号,数值从 0 开始,所以第一章的 ChapterIndex 为 0
ChapterId String 章节 id
CustomServerParams String 透传自定义内容
Source Number 0 - 插件预加载对应章节,不是用户实际读;1 - 用户读到对应章节;开发者可针对Source=1做自动解锁逻辑
ChapterOriginalId String 章节主键 original_id,如果开发者上传章节时没传 original_id,则 ChapterOriginalId 的值为空
BookOriginalId String 书籍主键 original_id,如果开发者创建作品时没传 original_id,则 BookOriginalId 的值为空
image.png
以JSON格式举例,XML格式是类似的
明文模式
{
	"ToUserName": "gh_xxx",
	"FromUserName": "orI6161IRrMgF3t3KfVFPOKf4nsk",
	"CreateTime": 1706085351,
	"MsgType": "event",
	"Event": "wxa_novel_chapter_permission",
	"BookId": "A1L2CaTvE3686DAK676Cqf372r",
	"ChapterIndex": 0,
	"ChapterId": "xxxxxx",
   "CustomServerParams":"test",
   "Source": 1
}

兼容模式
{
	"ToUserName": "gh_xxxxx",
	"FromUserName": "orI6161IRrMgF3t3KfVFPOKf4nsk",
	"CreateTime": 1706083040,
	"MsgType": "event",
	"Event": "wxa_novel_chapter_permission",
	"Encrypt": "V6GK8lE/L1SdPFYxzwXKg00hOSguFRaPwyKMQDmztT9aG/hN/4YBda9kqQfGgJjkOIhwYnTnWIuTwyZ+Ux+rqa/4r6wverGNny6EWp6UI0oBh6V/5ujqgk9CptjTPxuCFn/1ZthVeOBR/vRHXPAMgE1m1QTIb9HLpRnV/IcuufdHLz1zh0Gzeq/HiqNjYVcxbgxtxfDwAcBsVQZF1DUWr3rg9h6Y3nawW5UAra9kIsAgea0iXo/jPzwUEcfnUPMERBD8nBd7vDDhYtSrOD4Ywx9JuOqvMjULM3GzYqBffhVqUFSmQdkOBo0Qr6IK1CAjVw20vC0b5bmMJj+3JYIXVA==",
	"BookId": "A1L2CaTvE3686DAK676Cqf372r",
	"ChapterIndex": 2,
	"ChapterId": "xxxxxx",
	"CustomServerParams":"test"
}

加密模式
{
	"ToUserName": "gh_xxx",
	"Encrypt": "5BJZyHGl1XiZx05r2bO4YZJYoE6jGaDQAGg34pCID/C3zJv68i5ggOqbNdUDfFwL5iCSqv2cBnX2sX5+SgKp6Nr8PwGxajKdTEFUXDDYzf//hiEIZm1CdqwfVZAeKy7tDNz0q//ST8yO6ucRC1X/p4PUMHUayXU9DZQolfIsbiPIQ20gsq290T1n5HmnCIwuZfexqE9sRgVWTp3LnfmdgqPDVJe13Yv31FbYPC/1BXZfcRPEt0rWAvW1XtWSHeEbK2vKKQ/e1uzjChynTKHYUNwNEbD9JAkrNtdY5eHuIgaOxxvYGp/Rldnzg1kyTHSFs9y7BYGQw0WlpTabLBRzsg=="
}

# 回包格式

参数 类型 必填 说明
ErrCode Number 发送状态:0 - 成功;其他 - 失败
ErrMsg String 错误原因,用于调试。在 ErrCode 非 0 的情况下可以返回
ChapterPerms Array<ChapterPermission> 返回章节的具体解锁情况,鼓励开发者返回的 ChapterPerms 包含更多的章节解锁信息(包括已解锁和未解锁章节)

ChapterPermission 参数结构如下:

参数 类型 说明
StartChapterIndex Number 起始章节
EndChapterIndex Number 结束章节
Perm Number 0 - 免费;1 - 已解锁;2 - 未解锁
1:消息推送格式选JSON时,这里的回报格式也需要是json
注2:消息推送格式选XML时,这里的回报格式目前支持xml和json(优先推荐xml格式,这里支持json只是为了兼容已接入的小程序)
注3:鼓励开发者返回的ChapterPerms包含更多的章节解锁信息(包括已解锁和未解锁章节)

{
	"ToUserName": "gh_xxx",
	"FromUserName": "orI6161IRrMgF3t3KfVFPOKf4nsk",
	"CreateTime": 1706085351,
	"MsgType": "event",
	"Event": "wxa_novel_chapter_permission",
	"BookId": "A1L2CaTvE3686DAK676Cqf372r",
	"ChapterIndex": 0,
	"ChapterId": "xxxxxx",
   "CustomServerParams":"test",
   "Source": 1
}

{
	"ErrCode": 0,
	"ErrMsg": "",
	"ChapterPerms": [{
		"StartChapterIndex": 0,
		"EndChapterIndex": 2,
		"Perm": 1
	}, {
		"StartChapterIndex": 3,
		"EndChapterIndex": 5,
		"Perm": 2
	}]
}

# 常见问题

拉取书籍内容时,跟付费链路异常有关的错误码:

错误码 原因
80002 开发者未配置消息推送
80003 消息推送链路有问题
80004 开发者回包格式有问题(可能返回 xml 格式)
80005 回包的 ErrCode 非 0,可能是开发者得业务逻辑有问题

# 附录

# 常见问题

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

{
  "lazyCodeLoading":"requiredComponents"
}

# 接入咨询

接入问题可咨询微信团队:

image.png

# 更新记录

插件详情页中也可以看到更新记录:

# 0.3.12

  1. 修复 paymentCompleted 传入 chapterIndex 值为 0 不生效的问题
  2. 提供 getCurrentNovelManager 接口用来获取当前插件页对应的 novelManger 实例
  3. 修复支付成功后重新拉取章节数据未触发 get_chapter 事件的问题
  4. 支持页面 page_show、page_hide、page_unload 事件
  5. 支持 disableAutoShowChargeDialog 参数用于关闭进入未解锁章节时自动拉起付费弹窗的特性
  6. 支持在非当前页时不渲染自定义段落的能力

# 0.3.11

  1. 调整强制观看广告段落的时长限制
  2. 修复 start_read 事件中 chapter_id 丢失问题
  3. 支持 get_chapter 事件,表示章节数据拉取完毕,会携带章节解锁状态参数
  4. 修复上下翻页时点击目录切换章节后直接退出没有保存阅读进度的问题

# 0.3.10

  1. 修复初始进入章节时,页码显示不准确的问题
  2. 优化初次进入时背景色切换表现
  3. setContents 兼容异常章节数据设置
  4. 自定义段落支持用后面的内容填充前一页的内容
  5. 自定义段落支持阻止翻页/滚动
  6. 支持隐藏解锁按钮、提示
  7. 支持配置化广告段落

# 0.3.9

  1. blockUnpaidScroll 默认值改为 1
  2. 重构渲染流程,优化其部分环节性能
  3. 优化进入阅读模式下的切页动画
  4. 调整解锁按钮模块的表现,新增 showButton 字段用来控制展示解锁按钮或 tips,默认安卓显示解锁按钮,iOS 显示 tips

# 0.3.4

  1. 支持 setLoggerConfig 接口用于控制播放器日志输出
  2. 在进入未解锁章节时默认拉起支付弹窗
  3. 修复介绍页书名超出一行后未居中的问题
  4. 修复平移翻页/覆盖翻页模式下的页码显示问题
  5. 去掉目录中“已付费”文案显示
  6. 目录页样式微调
  7. 修复设置弹窗拉起时,点击页面会同时响应切页的问题

# 0.3.3

  1. 修复当前章节不足一屏且设置 blockUnpaidScroll = 1 时无法向上滚动的问题
  2. 修复通过目录切换章节时的内容跳动问题

# 0.3.2

  1. 修复 blockUnpaidScroll 在某些场景不生效问题
  2. 优化上下翻页时购买按钮可能被遮挡问题