three.js
Repository: https://github.com/zestyxyz/zesty-ads-sdk-web/tree/main/threejs
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:
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();