hypelab-sdk v1.0.33

Hypelab Publisher SDK

The hypelab-sdk is a JavaScript SDK for writing applications that interact with the HypeLab ad servers from either Node.js, JS, or React Native environments. 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 Node.js, JS, and React Native
• Exposes the HypeLab API through the HypeLab Client

We highly suggest using the hypelab-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.

Installing the SDK

Grab the latest version of the SDK off of NPM:

npm install hypelab-sdk

Initializing a client

The HypeLab SDK can connect to Production and Staging environments. To initialize a client, simply pass in a config as follows:

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

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 should increase performance.

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

Formats

HypeLab offers a variety of ad formats. Different formats will work better for different dApps. It is best to consult with one of our HypeLab Experts to figure out what format will work best for your application.

Using the Native format

Native ads are highly customizable ads that allow you to match the look and feel of the ad with the look and feel of your application. The following is an example Native ad that can be constructed using the HypeLab SDK.

Creating a placement

A placement represent screen real estate on a property. If you want to show ads in multiple different places, it's highly recommended (for reporting and personalization purposes) to create multiple placements. Once you set up a placement in the HypeLab UI, you will receive a placement slug that acts as a unique identifier representing the placement. You can use this slug in order to make requests to the HypeLab servers.

Showing an ad

First, you will need to create real estate on the DOM where you would like the ad to be positioned. This div needs to have an id specified, which you will pass into the SDK.

<div id="native-slot"></div>

import { HypeLab, Environment, AdMetadata } from 'hypelab-sdk';

// initialize a HypeLab client
let client = new HypeLab({
  URL: 'https://api.hypelab-staging.com',
  propertySlug: 'dripdripdrip',
  environment: Environment.Production,
});

// initialize a native placement
let nativePlacement = client.initializeNative('<YOUR_PLACEMENT_SLUG>');

// register the placement and render it in the specified HTML element
nativePlacement.show('native-slot', nativeTemplate);

Creating a template

In the above example, you would have to create a nativeTemplate for the SDK to render. The SDK expects templates to be written in JSX. Here is an example of a native template:

// create a native template
function nativeTemplate(adMetadata: AdMetadata): JSX.Element {
  return (
    <div className="my-5">
      <div className="header-row text-white text-left">
        <span className="text-slate-600 mr-4">@{adMetadata.advertiser}</span>
        <span className="uppercase text-emerald-300">Advertisement</span>
      </div>
      <div className="body-row text-left">
        <div className="mt-3 text-white">{adMetadata.body}</div>
        <div className="mt-5">
          <a href={adMetadata.cta_url} target="_blank" rel="noreferrer">
            <div className="thumbnail">
              {adMetadata.creative_set_type == 'video' ? (
                <video
                  style={{ width: '100%' }}
                  poster={adMetadata.creative_set.poster}
                  src={adMetadata.creative_set.video}
                  autoPlay
                  muted
                  controls></video>
              ) : (
                <img
                  src={adMetadata.creative_set?.image}
                  alt="creative_img"
                  style={{ width: '100%' }}></img>
              )}
            </div>
            <button className="rounded-full bg-emerald-300 px-10 py-2 text-black font-bold mt-5">
              {adMetadata.cta_text}
            </button>
          </a>
        </div>
      </div>
    </div>
  );
}

The following fields are available on adMetadata to be used inside your template:

For creative_set_type of video, creative sets will look as follows.

"creative_set":{
	"video":"https://d1q98dzwj6s2rb.cloudfront.net/up/asset/2863530883/b83188c4f0.mp4",
	"icon":"https://d1q98dzwj6s2rb.cloudfront.net/up/asset/9f5c75d9d6/b83188c4f0.png",
	"poster":"https://d1q98dzwj6s2rb.cloudfront.net/up/asset/8fb3149953/b83188c4f0.png"
}

For creative_set_type of image, creative sets will look as follows.

"creative_set":{
	"icon":"https://d1q98dzwj6s2rb.cloudfront.net/up/asset/9f5c75d9d6/b83188c4f0.png",
	"image":"https://d1q98dzwj6s2rb.cloudfront.net/up/asset/8fb3149953/b83188c4f0.png"
}

Template Requirements

• Native design must clearly distinguish the ad from the app's content (e.g., BOOSTED tag)

• Images should not be cropped

• The background of the ad should not be clickable (e.g., no clickable whitespace)

• Content should not overlap the ad

Using the Rewarded format

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.

Including styles

To include the necessary styling for rewarded ads, import the hypelab css file:

import 'hypelab-sdk/dist/styles/hypelab.css';

Showing an ad

A rewarded ad can be loaded as follows:

let rewardedAd = client.initializeRewarded(<AD UNIT ID>);
await rewardedAd.show();

Rewarding a user

When the video is finished playing, the SDK will fire a callback to notify you to grant a reward to your user. You can listen to the callback as follows:

client.addRewardedEventListener('onRewardEarned', function() {
	// Grant a reward (e.g., Give an in-game item, unlock a paywall, etc.)
})