Skip to main content

three.js

Repository: https://github.com/zestyxyz/zesty-ads-sdk-web/tree/main/threejs

note

You will first need to create an ad unit on the marketplace in order to get started. Check out For Creators for more instructions.

Step 1 - Installing from NPM

Install the SDK from NPM like so:

npm install '@zestymarket/threejs-sdk'

Once installed, import the ZestyBanner component:

import * as Zesty from '@zestymarket/threejs-sdk';

Warning: Make sure you are using the same three.js version as the Zesty package, which you can check here.

If you are using an unsupported version, you can import a specific version of three.js from CDNs like Skypack: https://cdn.skypack.dev/three@version

Step 2 - Bringing the Zesty Banner into your scene

In the your scene setup, copy and paste:

const zestyBanner = new ZestyBanner("0", "billboard", "standard", 3);
scene.add(zestyBanner);

Replace "0" with your ad unit ID.

You can also pass optional arguments for the renderer (needed for WebXR) and beacon analytics:

const zestyBanner = new ZestyBanner("0", "billboard", "standard", 3, null, true);
scene.add(zestyBanner);

Step 3 - Customizing your banner display

These are the available attributes for your banner:

info

adUnit required

String: The ID of your ad unit.

format required

Determines the aspect ratio of your ad unit. Valid options are billboard, medium-rectangle, or mobile-phone-interstitial.

  • Billboard - 970 x 250
  • Mobile Phone Interstitial - 750 x 1334
  • Medium Rectangle - 300 x 250

format: { type: 'string', oneOf: ['billboard', 'medium-rectangle', 'mobile-phone-interstitial'] }

style required

String: The visual style of the default banner when no ad is being served. Valid options are "standard", "minimal", or "transparent".

height required

Integer: Scales the banner to your liking.

renderer optional

A reference to the three.js WebGLRenderer if you are making a WebXR experience. Can otherwise be omitted unless you are changing beacon settings, in which case it should be set to null.

beacon optional

Boolean: Setting beacon to false opts you out of Zesty analytics on your ad unit page.

Step 4 - Testing Locally

To test your integration locally with sample ads, add the ?debug=true flag to your URL (e.g., http://localhost:8080/?debug=true). This will load sample ads for testing purposes. Real ads will load when you deploy to production.

Source Reference

/**
* @constructor
* @param {string} adUnit The ad unit ID
* @param {string} format The format of the default banner
* @param {string} style The visual style of the default banner
* @param {Number} height Height of the banner
* @param {THREE.WebGLRenderer} renderer Optional field to pass in the WebGLRenderer in a WebXR project
* @param {boolean} beacon Whether to enable Zesty Analytics (defaults to true)
*/
constructor(adUnit, format, style, height, renderer = null, beacon = true) {
super();