notifications-sdk

Web3Analytic's javascript SDK for in-dapp notifications

Install

npm install @web3analytic/notifications-sdk

Usage

The most important function to import is registerImpression which takes as input an address (who may be interacting with your protocol on the frontend), and returns a prompt to show them that was created in the Web3Analytic frontend.

import { registerImpression } from '@web3analytic/notifications-sdk';

You may also want to check out web3analytic-react for a related React component that should be used in tandem with this SDK.

Applications

We provide walkthroughs for the common use cases.

In-Dapp Notifications

Import the following lines:

import { registerImpression } from '@web3analytic/notifications-sdk';
import { DappNotification } from '@web3analytic/notifications-react';

Now, you can render a component conditionally. For instance, here is an example of showing an in-dapp notification when a user connects an addess to MetaMask:

// Saves the ID of an impression
const [impressionId, setImpressionId] = useState(null);
// Saves the prompt returned by the SDK
const [notificationPrompt, setNotificationPrompt] = useState(null);
// Web3Analytic API key
const apiKey = ...

// ...more code...

/**
 * Callback for when an end-user connects their wallet to your dapp
 */
async function OnConnectToMetamask() {
  if (window.ethereum) {
    const provider = new ethers.providers.Web3Provider(window.ethereum);
    const signer = provider.getSigner();
    try {
      const address = await signer.getAddress();
      registerImpression(apiKey, address)
      .then(res => {
        if (res.impressionId) { setImpressionId(res.impressionId); }
        if (res.prompt) { setPrompt(res.prompt); }
      })
      .catch(err => {
        console.log('App `registerImpression` error:', err);
      });
    } catch (error) {
      console.log("web3analytic error", error);
    }
  }
}

// ...more code...

// We use `DappNotifications` from the `web3analytic-react` sdk to render a notification.
return (
  <DappNotification
    apiKey={apiKey}
    impressionId={impressionId}
    prompt={prompt}
  />
);

The impressionId is an identifier for the impression object produced by the SDK function registerImpression. This is used to record a reaction to the notification in DappNotification. The prompt object contains the metadata of what to show in the notification; it is also passed to DappNotification to render. The variable apiKey can be found in the Web3Analytic web application on the campaigns page.

Custom Notifications

Custom notifications are protocols that wish to customize the notifications beyond what we can do in the web application. The SDK provides two end points: (1) to register a custom impression in which the user can select usage, social, and wallet criteria, and (2) to register a reaction (e.g. did the user interact with the notification?). In this case, the SDK expects the user to provide their own frontend components.

Import the following lines:

import { registerCustomImpression, registerReaction } from '@web3analytic/notifications-sdk';

Here is the same example of an end-user connecting MetaMask but now with a custom notification:

// Import your own notification (replace this with your path)
import { myNotification } from './components/MyNotification.jsx';
// Saves the ID of an impression
const [impressionId, setImpressionId] = useState(null);
// Web3Analytic API key
const apiKey = ...

// ...more code...

/**
 * Callback for when an end-user connects their wallet to your dapp
 */
async function OnConnectToMetamask() {
  if (window.ethereum) {
    const provider = new ethers.providers.Web3Provider(window.ethereum);
    const signer = provider.getSigner();
    // This criteria says return all hits (no filters by usage, social, nor wallet)
    const criteria = {usage: null, social: null, wallet: null};
    try {
      const address = await signer.getAddress();
      registerCustomImpression(apiKey, address, criteria);
      .then(res => {
        if (res.impressionId) { setImpressionId(res.impressionId); }
      })
      .catch(err => {
        console.log('App `registerImpression` error:', err);
      });
    } catch (error) {
      console.log("web3analytic error", error);
    }
  }
}

/**
 * Function to handle an end-user reacting to a notification
 */
const handleOnReact = async () => {
  await registerReaction(apiKey, impressionId);
}

// ...more code...

// Use the callback in HTML / React / etc
<button onClick={() => { handleOnReact(); }}>

You can do more granular queries with custom notifications based on on-chain activity, social media activity, or wallet balances. For example, maybe you are interested in the subset of your segment who have done a referral campaign on GMX previously.

const criteria = {
  usage: {
    protocol: 'gmx',
    action: 'claim-referral',
    minCount: 0,
  },
  social: null,
  wallet: null,
};

Or you may be interested in those with at least 1k followers on Twitter:

const criteria = {
  usage: null,
  social: {
    channel: 'twitter',
    minFollowers: 1000,
  },
  wallet: null,
};

Or you may be interested in those with a 1k of usdc in their wallet:

const criteria = {
  usage: null;
  social: null;
  wallet: {
    minBalance: 0,
    tokens: {
      symbol: "usdc",
      minBalance: 1000
    }
  }
};