retargeting-sdk

Web3Analytic's javascript SDK for in-dapp retargeting

The goal of retargeting is to guide a user who has performed a source action to then perform a target action. A common example might be encouraging users to perform an on-chain swap after an approval.

Install

npm install @web3analytic/retargeting-sdk

Usage

The most important function to import is registerAction which takes as input an address interacting with your protocol frontend, along with information about an action.

import { registerAction } from '@web3analytic/retargeting-sdk';

You can register both on-chain and off-chain actions. For on-chain actions, you must provide the chain and the transaction hash (txHash). These can be obtained from any wallet provider (e.g. MetaMask) upon an on-chain action. It is not necessary to wait for a transaction to be confirmed.

import { registerAction, RegisterActionInputType }  from '@web3analytic/retargeting-sdk';
const input: RegisterActionInputType = {
  apiKey: "...",
  address: "0x...",
  chain: "ethereum",
  txHash: "0x...",
} 
registerAction(input).then(...)

For off-chain actions, an identifier must be provided. These strings can be of any length and structure although it is important it matches the identifiers chosen during setup of this retargeting campaign through the Web3Analytic web application.

import { registerAction, RegisterActionInputType }  from '@web3analytic/retargeting-sdk';
const input: RegisterActionInputType = {
  apiKey: "...",
  address: "0x...",
  identifier: "main-page-sidebar-button-click",
} 
registerAction(input).then(...)

Source and target actions are both registered using registerAction. The SDK will automatically detect whether the action is a source or target depending on the active retargeting campaigns. If the action is a source action, it will return an impression object:

{
  hit: true,
  prompt: {
    title: ...,
    subtitle: ...
    ...,
  }
  impressionId: 120;
}

The impressionId will be useful for regsitering reactions (see next). The prompt can be used to render a notification to encourage the user to take the corresponding target action.

If the action is a target action (or alternatively the action is not a match to any retargeting campaign), the returned object will only contain a single field hit set to false.

Analytics on conversion rates between source and target actions can be found on the Web3Analytic app.

Finally, we may be interested in the proportion of users that engage with a notification shown (irrespective of whether they take the target action or not). To track this, we can call the following

import { registerReaction }  from '@web3analytic/retargeting-sdk';

await registerReaction(apiKey, impressionId);

when the user engages with the notification prompt. Note that a user performing the target action is automatically tracked through registering actions and does not require calling registerReaction. Tracking user's clicking on the notification however, requires calling registerReaction.