@madfi/ts-sdk v0.2.0-alpha.5

Mad Finance SDK

This sdk intends to make it easy to

• fetch all of the ad campaigns that a publisher is receiving
• render pre-built react components for ad content
• log impressions via Privy

Installing

:warning: while this package is in private beta, export the shared npm token or set the variable in your app .env both locally in any ci/cd

NPM_TOKEN=

Install package via npm

npm i @madfi/ts-sdk --save

or yarn

yarn add @madfi/ts-sdk

Analytics Usage

You can use this sdk to track actions and user retention on your app via MadFi attribution.

addToGuestList: calls this when a user connects their wallet to identify unique monthly visitors

logAction: call this when a user performs an action you want to track in order to save relevant data to their privy account

Campaign Usage

You can use the pre-built React components or use the exposed functions to interact with the protocol directly

Adds an interface for campaign content:

{
  title: string;
  description: string;
  link?: {
    text: string;
    url: string;
  };
  creative?: {
    contentUri: string;
    alt: string;
    contentType: 'image/jpeg' | 'image/jpg' | 'image/png' | 'image/gif' | 'image/mp4' | 'video/mp4';
    videoEncoding?: string;
  };
}

Components

Wrap your React app with the MadfiProvider to manage state around viewable and viewed content

...
import { MadfiProvider } from '@madfi/ts-sdk';

const App = ({ Component, pageProps }: AppProps) => (
  <MadfiProvider
    receiverAddress="0x..." //required
    tags=["music", "cinema"] // optional
  >
    <Component {...pageProps} />
  </MadfiProvider>
);

...

The receiver address needs to be your publisher address on Polygon, which is the address that the Superfluid stream is going to. Tags is an optional parameter that you can use to only get campaigns with a specific tag. This would take effect for all ads that are rendered inside of the provider.

Put a MadPlacement component anywhere you'd like to show an ad.

import { MadPlacement } from '@madfi/ts-sdk';
...

<MadPlacement
  placementType={1} // required
  styles={{ borderRadius: 0 }} // optional
  lens={{ include: true, mainnet: true }} // optional
  tags=["music", "cinema"] // optional
/>

...

You can pass in custom values for borderRadius, backgroundColor and textColor (default is 8px radius, white background, black text) and you can optionally have the ad placement include the Lens username of the advertiser (if they have a Lens account) with the lens prop. If you supply a value for the optional tags prop then this placement component will only show an ad that has that tag.

For the placementType prop reference the ad content placement guide for usable dimensions. Each of these is referencable via the PlacementType enum in constants.ts:

export enum PlacementType {
  'Square',
  'Small Square',
  'Banner',
  'Leaderboard',
  'Inline Rectangle',
  'Large Rectangle',
  'Skyscraper',
  'Wide Skyscraper',
  'Half Page Ad',
  'Large Leaderboard',
}

Direct interaction

You can also interact with the protocol directly

Fetch Campaigns

interface QueryArgs {
  connected: boolean; // true if there is a connected account
  address?: string; // required if connected == true
  tags?: string[]; // filter for campaigns with these tags
  trustTokensOnly?: boolean; // only fetch campaigns from connected user's tokens
}

/**
 * GQL query for active campaigns
 * @param QueryArgs
 * @returns active campaigns user has opted into
 */
export const getCampaigns = async ({
  address,
  trustTokensOnly = false,
  connected,
  tags,
}: QueryArgs): Promise<Campaign[]> => ...

Save Impressions

Log an impression with the wallet of the connected user or with the default store if none connected

export type ImpressionType = 'view' | 'click' | 'mint';

export const writeImpression = async (
  campaign: Campaign,
  impression: ImpressionType
) => ...

Fetch Ad Content from IPFS

Fetch JSON content

export const getAdContent = async (contentURI: string) => ...

Wrap image URI with the MadFi gateway for use in HTML img tags

export const withGateway = (contentURI: string) => ...