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.

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.

Sample code snippets are available on the HypeLab Github.

React Integration Guide

If your project is using Typescript, first install the @hypelab/sdk-react package which provides strongly typed HypeLab components:

Command Line

Copy

npm install @hypelab/sdk-react

Next, include the HypeLab SDK in the head tag of your page and set the following required parameters in the script tag:

Field	Value	Description
`environment`	`production` or `development`	Set debugging information output
`property_slug`	Your site slug (e.g., `3eb413c651`)	Your unique Website or app identifier

NextJS

Use next/script to load the script in the root layout of your project.

src/app/layout.tsx

Copy

<Script
  id="hypelab"
  strategy="afterInteractive"
  dangerouslySetInnerHTML={{
    __html: `!(function (h, y, p, e, l, a, b) {
    ((a = document.createElement(h)).async = !0),
      (a.src = y),
      (a.onload = function () {
        (l = { environment: p, propertySlug: e, ...l }), HypeLab.initialize(l);
      }),
      (b = document.getElementsByTagName(h)[0]).parentNode.insertBefore(b, a);
  })('script', 'https://api.hypelab.com/v1/scripts/hp-sdk.js?v=0', '<environment>', '<property_slug>', {});`,
  }}
/>

To disable automatic wallet detection, change the last parameter in the function call from {} to { privacy: { disableWalletDetection: true } }

Remix

Add the script to your app/root.tsx file, and set suppressHydrationWarning={true} on the <script> element:

app/root.tsx

Copy

<script
  suppressHydrationWarning={true}
  dangerouslySetInnerHTML={{
    __html: `!(function (h, y, p, e, l, a, b) {
    ((a = document.createElement(h)).async = !0),
      (a.src = y),
      (a.onload = function () {
        (l = { environment: p, propertySlug: e, ...l }), HypeLab.initialize(l);
      }),
      (b = document.getElementsByTagName(h)[0]).parentNode.insertBefore(b, a);
  })('script', 'https://api.hypelab.com/v1/scripts/hp-sdk.js?v=0', '<environment>', '<property_slug>', {});`,
  }}
/>

To disable automatic wallet detection, change the last parameter in the function call from {} to { privacy: { disableWalletDetection: true } }

Ad Callbacks

We provide two callbacks on all of the placements: onReady and onError. The onReady callback is triggered when an ad is successfully loaded and is ready to be shown. The onError callback is triggered when an ad is unsuccessfully loaded. This may happen for several reasons including frequency capping, bot detection, or periods of low ad demand. Below is an example of how to implement the onReady and onError callback.

export default function Page() {
  const onReady = () => {
    console.log('onReady');
  };

  const onError = () => {
    console.log('onError');
  };

  return (
    <Banner placement="banner_placement" onReady={onReady} onError={onError} />;
  );
}

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.

Copy

import { useEffect } from "react";
import { setWalletAddresses } from "@hypelab/sdk-react";

export default function Page() {
  useEffect(() => {
    setWalletAddresses(["0x123...", "0x234..."]);
  }, []);

  /* rest of code */
}

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!

The banner method allows the HypeLab SDK to identify where to insert the banner ad. The banner method takes in an object that contains your placement_slug (e.g., banner_placement) and a container where the ad should be rendered.

src/app/banner/page.tsx

Copy

'use client';

import { Banner } from '@hypelab/sdk-react';

export default function Page() {
  return <Banner placement="banner_placement" />;
}

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.

Child elements inherit your styles and are identified by their data-ref attribute. The SDK will auto-populate the following data-ref values:

Field	HTML Tag	Description
`advertiser`	`span`, `div`, `p`	Advertiser name (e.g., Uniswap)
`body`	`span`, `div`, `p`	Secondary body text
`ctaLink`	`a`	Destination for the call-to-action
`ctaText`	`span`, `div`, `p`	Call-to-action text (e.g., Get started)
`displayUrl`	`span`, `div`, `p`	Display URL for the ad (e.g., uniswap.org)
`headline`	`span`, `div`, `p`	Primary headline text
`icon`	`img`	Icon of the advertiser or dApp
`mediaContent`	`div`	Media content of the ad, either a video or an image

src/app/native/page.tsx

Copy

"use client";

import { Native } from "@hypelab/sdk-react";

export default function Page() {
  return (
    <Native placement="native_placement">
      <div className="bg-black p-5 w-[728px]">
        <div className="relative flex items-center">
          <div className="flex-shrink-0">
            <img data-ref="icon" className="h-10 w-10 rounded-full mr-5" />
          </div>
          <div className="min-w-0 flex-1">
            <span className="absolute inset-0" aria-hidden="true"></span>
            <p className="font-medium text-slate-400">
              @<span data-ref="advertiser"></span>
            </p>
            <p data-ref="displayUrl" className="text-emerald-300 text-sm"></p>
          </div>
        </div>
        <div data-ref="body" className="mt-3 text-white"></div>
        <div className="body-row text-left">
          <div data-ref="headline" className="mt-3 text-white"></div>

          <div className="mt-5">
            <a data-ref="ctaLink" href="/" target="_blank" rel="noreferrer">
              <div data-ref="mediaContent" className="mediaContent h-fit"></div>
              <div
                data-ref="ctaText"
                className="rounded-full bg-emerald-300 px-10 py-2 text-black font-bold mt-5 text-center"
              ></div>
            </a>
          </div>
        </div>
      </div>
    </Native>
  );
}

Tip: To make the Native ad more reusable, consider creating a NativeComponent.

Rewarded

Rewarded ads allow users to explicitly opt-in to view an ad in exchange for some kind of reward. 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.

To show the rewarded video, define a ref and then use the show method on the Rewarded component.

There are three callbacks that can be passed to the Rewarded component: onReady, onError, and onReward.

The onReady and onError events signify that an ad was loaded or that an ad failed to load. See Ad Callbacks for more details. Typically, you should wait until the onReady callback is called before allowing the user to trigger the rewarded ad. In the example below, we enable the rewarded button in the onReady callback.
The onReward event signifies that the video ad was played to completion. In the example below, we trigger a reward distribution in the onReward callback.

The show input should be a state that informs the Rewarded component when to appear on screen.

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 onReward to issue a reward and reset the show variable.

src/app/rewarded/page.tsx

Copy

"use client";

import { useRef, useState } from "react";
import { Rewarded, RewardedElement } from "@hypelab/sdk-react";

export default function Page() {
  // Create a ref for the rewarded component
  const rewarded = useRef<RewardedElement>(null);
  const [disabled, setDisabled] = useState(true);

  // Show rewarded video
  const showRewarded = () => rewarded.current?.show();

  // Event handlers
  const onReady = () => {
    console.log("onReady");
    setDisabled(false);
  };

  const onReward = () => {
    console.log("onReward");
    setDisabled(true);
  };

  const onError = () => {
    console.log("onError");
    setDisabled(true);
  };

  return (
    <>
      <Rewarded
        placement="rewarded_placement"
        ref={rewarded}
        onReady={onReady}
        onError={onError}
        onReward={onReward}
      />
      <button
        type="button"
        className="block p-2.5 bg-blue-600 text-white disabled:bg-gray-400"
        disabled={disabled}
        onClick={showRewarded}
      >
        Show Rewarded
      </button>
    </>
  );
}