# 介绍

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

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

# 效果示例

# 代码示例

代码片段示例

# 接入流程

# 添加插件

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

首先需要在小程序的 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'
})

支持参数：

注意：

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

# 章节解锁组件

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

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

首先需要编写一个自定义组件 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"
        }
      }
    }
  }
}

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

注意：

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

# 接口列表

# novelPlugin

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

const novelPlugin = requirePlugin('novel-plugin')

# novelPlugin.onPageLoad(Function callback)

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

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

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

# NovelManager novelPlugin.getNovelManager(Number id)

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

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

const novelManager = novelPlugin.getNovelManager(id)

# novelPlugin.setLoggerConfig(Object params)

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

params 参数结构如下：

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

# NovelManager

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

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()

获取阅读器信息。

返回参数结构如下：

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

const pluginInfo = novelManager.getPluginInfo()

# Object NovelManager.getLaunchOptions()

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

const launchOptions = NovelManager.getLaunchOptions()

# NovelManager.onPluginError(Function callback)

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

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

novelManager.onPluginError(res => {
  // do something
})

# String NovelManager.getCustomServerParams()

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

const customServerParams = novelManager.getCustomServerParams()

# NovelManager.setCustomServerParams(Object params)

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

params 参数结构如下：

novelManager.setCustomServerParams({
  customServerParams: 'xxx'
})

# NovelManager.setClosePluginInfo(Object params)

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

params 参数结构如下：

novelManager.setClosePluginInfo({
  url: '/pages/tab/index',
  mode: 'switchTab',
})

# NovelManager.setShareParams(Object params)

设置分享书籍时的参数。

params 参数结构如下：

// 关闭分享
novelManager.setShareParams({
  enable: false,
})

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

# NovelManager.setBookshelfStatus(Object params)

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

params 参数结构如下：

novelManager.setBookshelfStatus({
  bookshelfStatus: 1,
})

# NovelManager.onClickBookshelf(Function callback)

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

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

novelManager.onClickBookshelf(res => {
  // do something

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

# NovelManager.setActivity(Object params)

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

params 参数结构如下：

novelManager.setActivity({
  url: '/pages/activity/index',
})

# NovelManager.setContents(Object params)

设置目录。

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

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

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

params 参数结构如下：

Content 参数结构如下：

novelManager.setContents({
  contents: [
    {
      index: 0, // 第一章
      status: 0,
    },
    {
      index: 1, // 第二章
      status: 2,
    },
    {
      index: 2, // 第三章
      status: 1,
    },
  ],
})

# NovelManager.setChargeWay(Object params)

设置章节解锁方式。

params 参数结构如下：

SetChargeWayItem 参数结构如下：

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

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

# NovelManager.paymentCompleted(Object params)

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

params 参数结构如下：

novelManager.paymentCompleted()

# NovelManager.openChargeDialog(Object params)

拉起章节解锁组件。

params 参数结构如下：

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

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

# NovelManager.closeChargeDialog()

关闭章节解锁组件。

novelManager.closeChargeDialog()

# NovelManager.onUserClickAdUnlock(Function callback)

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

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

novelManager.onUserClickAdUnlock(res => {
  // do something
})

# NovelManager.onUserClickCustomUnlock(Function callback)

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

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

novelManager.onUserClickCustomUnlock(res => {
  // do something
})

# NovelManager.onUserTriggerEvent(Function callback)

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

事件基础参数如下：

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

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)

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

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

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

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

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

ChapterParagraphBlock 参数结构如下：

ParagraphBlock 参数结构如下：

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

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 参数结构如下：

ChapterAdBlock 参数结构如下：

AdBlock 参数结构如下：

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

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

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

# NovelManager.setFullScreenComponentStatus(Object params)

插入全屏组件。

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

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

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

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

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

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。

# 章节解锁链路

# 消息推送

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

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

注意：这里消息推送超时时间为4s（常规消息推送是5s）。

# 消息格式

# 接收的数据格式

以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=="
}

# 回包格式

ChapterPermission 参数结构如下：

注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
	}]
}

# 常见问题

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

# 附录

# 常见问题

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

{
  "lazyCodeLoading":"requiredComponents"
}

# 接入咨询

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

# 更新记录

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

# 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. 优化上下翻页时购买按钮可能被遮挡问题