Getting started

TIP

Using React? Check out the React SDK documentation.

Installation

NPM

You can install the SDK into your project using NPM:

npm

npm install @adhese/sdk

pnpm

pnpm add @adhese/sdk

yarn

yarn add @adhese/sdk

bun

bun add @adhese/sdk

JS file

You can also include the SDK in your project by including the following script tag in your HTML. Download the latest version.

<script src="./files/adhese.js"></script>

Usage

To use the SDK, you need to create an Adhese instance and configure it with your account ID:

const adhese = createAdhese({
  account: 'your-account-id',
});

Automatically find slots on the page

The SDK can automatically find all slots on the page and load them. This is the easiest way to get started:

const adhese = createAdhese({
  account: 'your-account-id',
  findDomSlotsOnLoad: true,
});

Slots are found by looking for elements with the adunit class. The element is required to have a data-format="YOUR_FORMAT" attribute set on the element to know which format needs to be fetched.

Example DOM slots:

<div class="adunit" data-format="billboard"></div>

Fetching slots before DOM is ready

If you want to fetch slots before the DOM is ready, you can pass the initialSlots option to the createAdhese function. This is particularly useful if you want to start the fetching process as soon as possible. Downside is that you need to know which slots are going to be on the page on beforehand.

const adhese = createAdhese({
  account: 'your-account-id',
  initialSlots: [
    {
      containingElement: 'slot-1', // ID of the element that contains the slot
      format: 'billboard',
    },
    {
      containingElement: 'slot-2', // ID of the element that contains the slot
      format: 'leaderboard',
    },
  ],
});

Example HTML:

<div id="slot-1" class="adunit" data-format="billboard"></div>
<div id="slot-2" class="adunit" data-format="leaderboard"></div>

Options

The createAdhese function accepts the following options:

Option	Type	Default	Description
account*	string	-	Your Adhese account ID
host	string	'https://ads-{{account}}.adhese.com'	The Adhese API host
poolHost	string	'https://pool-{{account}}.adhese.com'	The Adhese pool host
location	string	window.location.pathname	The page location. This is used to determine the current page location identifier.
requestType	'GET' or 'POST'	'POST'	The requestAds type to use for the Adhese API requests. This can be either GET or POST. POST is the default and offers the most options. GET is more limited as it needs pass its data as search parameters but can be used in environments where POST requests are not allowed.
debug	boolean	false	Enable debug mode
findDomSlotsOnLoad	boolean	false	Automatically find slots on the page and load them
parameters	Record<string, string, Array<string>>	{}	Additional parameters to send with each request. Make sure that the keys of a parameter only contain 2 characters.
consent	boolean	false	User consent for tracking
initialSlots	Array<Slot>	[]	Slots to fetch before the DOM is ready
logReferrer	boolean	true	Will log the document.referrer to the Adhese API in a BASE64 string with the re parameter.
logUrl	boolean	true	Will log the location.href to the Adhese API in a BASE64 string with the ur parameter.
eagerRendering	boolean	false	Will render the ad as soon as it is fetched. In general it is recommended to keep this false for better performance.
queries	Record<string, string>	{phone: '(max-width: 768px) and (pointer: coarse)',tablet: '(min-width: 769px) and (max-width: 1024px) and (pointer: coarse)',desktop: '(min-width: 1025px) and (pointer: fine)',}	Will be used to determine the device type and screen size. The matching query key will be passed in the dt and br parameter.
plugins	ReadonlyArray<(context: AdheseContext) => void>	[]	The plugins that are used for the Adhese instance. These plugins are called with the Adhese context and run during the initialization of the Adhese instance.

* Required