Joyfun

Taro 小程序接入 ​

注意事项

接入前请移除全局配置中的 lazyCodeLoading 属性，否则在低版本基础库中会导致页面白屏。

一、下载组件 ​

下载地址：广告组件下载
解压后将文件夹放在和 pages 同级的 components 目录下。若没有该目录，请自行创建。

二、声明插件和广告组件 ​

在 app.config.js 中声明需要使用的插件以及广告组件

js
export default defineAppConfig({
  usingComponents: {
    'joyfun-ad': 'components/joyfun/joyfun-ad/joyfun-ad',
    'joyfun-splash-ad': 'components/joyfun/joyfun-splash-ad/joyfun-splash-ad',
    'joyfun-interstitial-ad':
      'components/joyfun/joyfun-interstitial-ad/joyfun-interstitial-ad',
    'joyfun-reward-video-ad':
      'components/joyfun/joyfun-reward-video-ad/joyfun-reward-video-ad',
  },
  plugins: {
    joyfunPlugin: {
      version: 'latest',
      provider: 'wx9fb5a4d00ee53501',
      export: 'components/joyfun/export.js',
    },
  },
})

修改 config/index.js 的部分配置

js
export default defineConfig(async (merge, { command, mode }) => {
  const baseConfig = {
    plugins: [
      [
        '@tarojs/plugin-framework-vue3',
        {
          vueLoaderOption: {
            compilerOptions: {
              //防止小程序开发者控制台对于joyfun自定义组件未识别的警告
              isCustomElement: (tag) => tag.includes(`joyfun-`),
            },
          },
        },
      ],
    ],
    copy: {
      patterns: [
        //复制文件到编译后的指定目录
        {
          from: 'src/components/joyfun/export.js',
          to: 'dist/components/joyfun/export.js',
        },
      ],
    },
  }
})

三、广告组件的使用 ​

组件参数

appId - 应用 ID，由运营提供
adId - 广告位 ID，由运营提供
miniUid - 用户 id，由小程序自己定义，用于广告数据的调试和排查
extra - 激励视频服务端回调的透传内容，仅在开启服务端回调时生效 (若为对象或数组，请转为 json 字符串)

组件事件回调

adload - 广告加载完成
adshow - 广告展示
adreward - 激励视频观看指定时间后关闭
adclose - 广告关闭
aderror - 广告报错

组件方法

load - 加载广告
show - 展示广告
close - 关闭广告

原生模板、悬浮广告 ​

html
<joyfun-ad
  :app-id="appId"
  :ad-id="bannerAdId"
  :mini-uid="miniUid"
  @adload="adLoad"
  @adshow="adShow"
  @aderror="adError" />

全屏广告 ​

html
<joyfun-splash-ad
  id="joyfun-splash-ad"
  :app-id="appId"
  :ad-id="splashAdId"
  :mini-uid="miniUid"
  @adload="splashLoad"
  @adshow="splashShow"
  @adclose="splashClose"
  @aderror="splashError" />
js
import { getCurrentInstance, useLoad, nextTick } from '@tarojs/taro'

let splashAd = null

useLoad(() => {
  //为确保组件加载完成，请在 nextTick 中进行获取实例
  nextTick(() => {
    //获取全屏组件实例
    splashAd = getCurrentInstance().page.selectComponent('#joyfun-splash-ad')
    //若需要立即调用，请添加定时器，否则可能报错
    setTimeout(() => {
      //加载全屏，调用时机可自行调整
      splashAd.load()
    }, 200)
  })
})
//全屏加载完成回调
function splashLoad() {
  //展示全屏，调用时机可自行调整
  splashAd.show()
}
//全屏展示回调
function splashShow() {}
//全屏关闭回调
function splashClose() {}
//全屏报错回调
function splashError(err) {}

插屏广告 ​

html
<joyfun-interstitial-ad
  id="joyfun-interstitial-ad"
  :app-id="appId"
  :ad-id="interstitialAdId"
  :mini-uid="miniUid"
  @adload="interstitialLoad"
  @adshow="interstitialShow"
  @adclose="interstitialClose"
  @aderror="interstitialError" />
js
import { getCurrentInstance, useLoad, nextTick } from '@tarojs/taro'

let interstitialAd = null

useLoad(() => {
  //为确保组件加载完成，请在 nextTick 中进行获取实例
  nextTick(() => {
    //获取插屏组件实例
    interstitialAd = getCurrentInstance().page.selectComponent(
      '#joyfun-interstitial-ad'
    )
    //若需要立即调用，请添加定时器，否则可能报错
    setTimeout(() => {
      //加载插屏，调用时机可自行调整
      interstitialAd.load()
    }, 200)
  })
})
//插屏加载完成回调
function interstitialLoad() {
  //小程序启动后无法立即展示插屏，请自行设置至少5秒延时
  //展示插屏，调用时机可自行调整
  interstitialAd.show()
}
//插屏展示回调
function interstitialShow() {}
//插屏关闭回调
function interstitialClose() {}
//插屏报错回调
function interstitialError(err) {}

激励视频 ​

html
<joyfun-reward-video-ad
  id="joyfun-reward-video-ad"
  :app-id="appId"
  :ad-id="rewardedVideoAdId"
  :mini-uid="miniUid"
  :extra="extra"
  @adload="rewardVideoLoad"
  @adshow="rewardVideoShow"
  @adreward="rewardVideoReward"
  @adclose="rewardVideoClose"
  @aderror="rewardVideoError" />
js
import { getCurrentInstance, useLoad, nextTick } from '@tarojs/taro'

let rewardVideoAd = null

useLoad(() => {
  //为确保组件加载完成，请在 nextTick 中进行获取实例
  nextTick(() => {
    //获取激励组件实例
    rewardVideoAd = getCurrentInstance().page.selectComponent(
      '#joyfun-reward-video-ad'
    )
    //若需要立即调用，请添加定时器，否则可能报错
    setTimeout(() => {
      //加载激励，调用时机可自行调整
      rewardVideoAd.load()
    }, 200)
  })
})
//激励加载完成回调
function rewardVideoLoad() {
  //展示激励，调用时机可自行调整
  rewardVideoAd.show()
}
//激励展示回调
function rewardVideoShow() {}
//激励观看指定时长后关闭回调
function rewardVideoReward() {}
//激励关闭回调
function rewardVideoClose(res) {}
//激励报错回调
function rewardVideoError(err) {}

关于服务端回调说明

若小程序需要服务端的激励回调，请向运营提供对应的回调地址。
服务器会以 GET 方式请求第三方服务的回调地址，并拼接以下参数回传：

appid=APPID&pid=PID&sign=SIGN&transid=TRANSID&userid=USERID&extrainfo=EXTRAINFO

回调传参
appid - 媒体 ID
pid - 广告位 ID
userid - 传入广告组件的用户 ID
transid - 交易 ID
sign - 签名
extrainfo - 传入激励广告组件的透传内容，并已进行 UrlEncode 编码

签名生成方式

secret - 激励回调的秘钥，由运营提供

js
sign = sha256(transid + secret)

服务端收到通知后，请按如下json格式进行响应

json
{
  "isValid": true
}

活动页 ​

接入活动页前，需对app.config.js中插件声明部分进行补充

js
export default defineAppConfig({
  plugins: {
    joyfunPlugin: {
      version: 'latest',
      provider: 'wx9fb5a4d00ee53501',
      export: 'components/joyfun/export.js',
      genericsImplementation: {
        'points-mall': {
          'comp-ad': '/components/joyfun/comp-ad/comp-ad',
        },
      },
    },
  },
})

跳转活动页

js
Taro.navigateTo({
  url: `plugin://joyfunPlugin/active-page?appId=${appId}&adId=${activePageAdId}&miniUid=${miniUid}`,
})

四、在分包内引入插件 ​

若小程序主包剩余容量不足，想在分包中引入插件，可参考如下配置。

js
export default defineAppConfig({
  subpackages: [
    {
      root: 'subpages1',
      pages: ['index/index'],
      plugins: {
        joyfunPlugin: {
          version: 'latest',
          provider: 'wx9fb5a4d00ee53501',
          //将joyfun文件夹内的export.js文件复制到该分包的根目录
          export: 'export.js', 
        },
      },
    },
  ],
})

调整 config/index.js 的 copy 配置

js
export default defineConfig(async (merge, { command, mode }) => {
  const baseConfig = {
    copy: {
      patterns: [
        //subpages1为分包的目录名
        { from: 'src/subpages1/export.js', to: 'dist/subpages1/export.js' },
      ],
    },
  }
})

提示

跨分包调用广告组件时，需要时间来异步加载广告插件，调用广告方法时请先判断广告组件实例是否已存在。