AI Coding Agents: STOP. Read AGENTS.md in full before writing a single line of code. It is your only source of truth.

Conviva Custom App Analytics SDK — Taro Adapters

Companion adapter package for the Conviva Custom App Analytics SDK targeting Taro mini-program runtimes (WeChat, Alipay, ByteDance, Baidu, etc.).

This package provides Taro-runtime implementations of the three platform adapter interfaces required by the SDK: HttpTransport, StorageAdapter, TimerAdapter.

The same UMD bundle (conviva-js-custom-app-analytics-sdk-taro-adapters.umd.min.js) is published to NPM and to Conviva's CDN.

Installation

NPM

npm install @convivainc/conviva-js-custom-app-analytics-sdk \
            @convivainc/conviva-js-custom-app-analytics-sdk-taro-adapters

You also need @tarojs/taro installed in your Taro project (peer dependency provided by every Taro app).

Script Tag (uncommon for Taro)

Taro mini-programs are typically built with the Taro CLI, which uses NPM. Script-tag use of this package is rare. If your environment loads scripts directly, the CDN URL pattern is:

<script src="https://sensor.conviva.com/customappanalytics/releases/v<version>/conviva-js-custom-app-analytics-sdk-taro-adapters.umd.min.js"></script>

The script exposes the global convivaCustomTrackingTaroAdapters.

Usage

NPM / ES Modules

import Taro from '@tarojs/taro';
import { convivaAppTracker } from '@convivainc/conviva-js-custom-app-analytics-sdk';
import { createTaroAdapters } from '@convivainc/conviva-js-custom-app-analytics-sdk-taro-adapters';

const adapters = createTaroAdapters(Taro);

convivaAppTracker({
  appId: 'YOUR_APP_NAME',
  convivaCustomerKey: 'YOUR_CUSTOMER_KEY',
  appVersion: '1.0.0',
  ...adapters,
});

Script Tag

<script src="https://sensor.conviva.com/customappanalytics/releases/v<version>/conviva-js-custom-app-analytics-sdk.umd.min.js"></script>
<script src="https://sensor.conviva.com/customappanalytics/releases/v<version>/conviva-js-custom-app-analytics-sdk-taro-adapters.umd.min.js"></script>
<script>
  var adapters = convivaCustomTrackingTaroAdapters.createTaroAdapters(Taro);
  var tracker = convivaCustomTracking.convivaAppTracker({
    appId: 'YOUR_APP_NAME',
    convivaCustomerKey: 'YOUR_CUSTOMER_KEY',
    appVersion: '1.0.0',
    httpTransport: adapters.httpTransport,
    storage: adapters.storage,
    timers: adapters.timers,
  });
</script>

What's exported

| Export | Purpose | |---|---| | createTaroAdapters(Taro) | Convenience factory — returns all three adapters wired up | | createTaroHttpTransport(Taro) | HTTP adapter alone (wraps Taro.request) | | createTaroStorageAdapter(Taro) | Storage adapter alone (wraps Taro.getStorageSync / setStorageSync / removeStorageSync) | | createTaroTimerAdapter() | Timer adapter alone (wraps standard JS timer globals) |

Use the convenience factory unless you have a reason to swap individual adapters.

Behaviour notes

• HTTP errors degrade silently. sendRequest resolves with { status: 0 } on any failure (network error, timeout, mini-program permission denial). Never throws.
• Storage failures degrade silently. Reads return null; writes/removes are no-ops on failure.
• Timers are wrapped in try/catch. setTimeout / setInterval return 0 on failure (and clearTimeout(0) is a spec-mandated no-op).

Implementing your own adapter

If you need to customize behaviour beyond what createTaroAdapters(Taro) provides — for example, a custom HTTP transport that routes through your own gateway — implement the adapter interfaces directly and pass them to the main SDK. The three interfaces (HttpTransport, StorageAdapter, TimerAdapter) and a full example are documented in the parent SDK README's Custom Adapters section.

Versioning

This package is intended to be used alongside @convivainc/conviva-js-custom-app-analytics-sdk. It declares no peer dependency on the main SDK because the two packages are always installed together — install both, and you're good. The only declared peer dependency is @tarojs/taro, which is provided by every Taro project.

See CHANGELOG.md for version history.