hypelab-react v0.5.0

HypeLab Publisher SDK

The HypeLab SDK is a JavaScript SDK for writing applications that interact with the HypeLab ad servers from various front-end JS frameworks (e.g., React, Vue, etc.). The SDK provides a simple interface for application builders and abstractions for core data structures, ad rendering, and API request generation.

Features

• SDK is written in TypeScript, with type definitions
• Works in React and other JS frameworks
• Exposes the HypeLab API through the HypeLab Client

We highly suggest using the SDK with TypeScript, or JavaScript in a code editor that has support for type declarations, so you can take advantage of the helpful type hints that are included with the package.

React Integration Guide

Grab the latest version of the React SDK by running npm install --save hypelab-react.

Initializing a client

Navigate to your root React component. Usually you'll find this in src/index.js.

Import HypeLab and initialize a client using your propertySlug.

import { HypeLab, HypeLabContext, Environment } from 'hypelab-react';

let client = new HypeLab({
    URL: 'https://api.hypelab-staging.com',
    // URL: 'https://api.hypelab.com', /* Production URL */
    propertySlug: '<PROPERTY_SLUG>',
    environment: Environment.Development
    // environment: Environment.Production /* Production Environment */
});

Now that you've set up a new HypeLab client, you need to tell your app that it's ready to be used. Find the render function and wrap the root component in a HypeLabContext using the client. The context helps HypeLab pass data through the component tree without requiring you to set tons of component props.

<HypeLabContext client={client}>
    <App />
</HypeLabContext>

Setting a wallet address

If a user has connected their wallet, you can pass the wallet address to the SDK as follows. Setting a wallet is optional but helps us show the most relevant ad for the user, which in turn will help us personalize ads and ensure we can maximize your earned CPM.

client.identity.setWalletAddresses(['0x123...', '0x234...']);

Alternatively, there is a React hook that makes it easier to set wallet addresses within the HypeLab context.

import { useIdentity } from 'hypelab-react';

const { setWalletAddresses } = useIdentity();
setWalletAddresses(['0x123...', '0x234...']);

Formats

Now that your app is configured, you can start placing ads in any of your React components!

Banner

Banner ads are static placements that typically display image assets. If you're new to ads monetization, they are a great place to start! First, import the Banner component from HypeLab.

import { Banner } from 'hypelab-react';

Add the Banner component as needed using the placement's slug.

<Banner placement="<PLACEMENT_SLUG>" />

The size of the banner placement can be set during the placement creation process on the HypeLab UI. Please reach out to your account manager for more information.

Native

Native ads are highly customizable ads that allow you to match the look and feel of an ad with the look and feel of your application. The following is an example Native component that uses the HypeLab SDK to render an ad template.

The useNative hook allows the HypeLab SDK to hook into your template and insert the relevant content.

import { HypeLabContext, Environment, HypeLab, Native, NativeLink, NativeMediaContent } from 'hypelab-react';

function SomeComponent() {
  return (
    <Native placement="<PLACEMENT_SLUG>">
      {ad => (
        <div className="bg-black p-5">
          <div className="relative flex items-center">
            <div className="flex-shrink-0">
              <img data-cy="icon" className="mr-5 h-10 w-10 rounded-full" src={ad.icon} />
            </div>
            <div className="min-w-0 flex-1">
              <span className="absolute inset-0" aria-hidden="true" />
              <p className="font-medium text-slate-400">
                @<span data-cy="advertiser">{ad.advertiser}</span>
              </p>
              <p data-cy="displayUrl" className="text-sm text-emerald-300">{ad.displayUrl}</p>
            </div>
          </div>
          <div className="body-row text-left">
            <div data-cy="headline" className="mt-3 text-white">{ad.headline}</div>

            <div data-cy="body" className="mt-3 text-white">{ad.body}</div>

            <div className="mt-5">
              <div data-cy="ctaLink">
                <NativeLink>
                  <div data-cy="mediaContent" className="mediaContent">
                    <NativeMediaContent />
                  </div>
                  <div
                    data-cy="ctaText"
                    className="mt-5 rounded-full bg-emerald-300 px-10 py-2 text-center font-bold text-black"
                  >{ad.ctaText}</div>
                </NativeLink>
              </div>
            </div>
          </div>
        </div>
      )}
    </Native>
  );
}

Next, you can simply add the SomeComponent component you just created to your React layout and it will render your native ad.

<SomeComponent />

Rewarded

Rewarded ads are served after a user explicitly chooses to view a rewarded ad. This puts the user in control of their in-app experience. Rewarded ads are shown to users in exchange for a reward that you control, such as an extra life or in-app currency. The best rewards are ones that are relevant to your users at the time they are deciding whether to opt-in to the rewarded experience.

When a user chooses to opt-in to the rewarded experience, an ad will open in a full-screen overlay and the video will autoplay without sound. Once the video playback is done, a callback is fired to let you know that it's time to reward the user.

First, import the Rewarded component from the HypeLab provider.

import { Rewarded } from 'hypelab-react';

There are two inputs suggested inputs to the Rewarded component: show and onComplete. The show input should be a state that informs the Rewarded component when to appear on screen. The onComplete is a function that is called when the rewarded modal is dismissed.

In the example below, we set the show variable to true when the user clicks on the "Watch Video" button. We have also added a handleRewarded function that is called onComplete to issue a reward and reset the show variable.

function SomeComponent() {
    const [show, setShow] = useState<boolean>(false);

    const handleWatch = async function () {
        setShow(true);
    };

    const handleRewarded = function () {
        // Grant a reward (e.g., Give an in-game item, unlock a paywall, etc.)
        console.log('handleRewarded called');
        setShow(false);
    };

    return (
        <>
            <div>
                <button
                    className="rounded-md border border-gray-300 bg-indigo-600 px-4 py-2 text-lg text-white"
                    onClick={handleWatch}
                >
                    Watch Video
                </button>
            </div>
            <Rewarded placement="<PLACEMENT_SLUG>" show={show} onComplete={handleRewarded} />
        </>
    );
}