@adhese/sdk 0.7.0 → 0.8.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +71 -41
- package/dist/index.cjs +751 -692
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.ts +87 -42
- package/dist/index.js +752 -693
- package/dist/index.js.map +1 -1
- package/package.json +12 -6
package/README.md
CHANGED
|
@@ -1,57 +1,87 @@
|
|
|
1
|
-
|
|
1
|
+
## Installation
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
everything from the root of the project.
|
|
3
|
+
### NPM
|
|
4
|
+
You can install the SDK into your project using NPM:
|
|
6
5
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
```
|
|
10
|
-
npm i
|
|
6
|
+
```bash
|
|
7
|
+
npm install @adhese/sdk
|
|
11
8
|
```
|
|
12
|
-
> Only use `npm` to install dependencies. `pnpm` and `yarn` will create their own lockfiles and will cause issues when
|
|
13
|
-
> maintaining the project.
|
|
14
9
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
10
|
+
## Usage
|
|
11
|
+
To use the SDK, you need to create an Adhese instance and configure it with your account ID:
|
|
12
|
+
|
|
13
|
+
```js
|
|
14
|
+
const adhese = createAdhese({
|
|
15
|
+
account: 'your-account-id',
|
|
16
|
+
});
|
|
19
17
|
```
|
|
20
18
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
`apps/example` will start a test server on `localhost:5173`.
|
|
19
|
+
### Automatically find slots on the page
|
|
20
|
+
The SDK can automatically find all slots on the page and load them. This is the easiest way to get started:
|
|
24
21
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
22
|
+
```js
|
|
23
|
+
const adhese = createAdhese({
|
|
24
|
+
account: 'your-account-id',
|
|
25
|
+
findDomSlotsOnLoad: true,
|
|
26
|
+
});
|
|
29
27
|
```
|
|
30
28
|
|
|
31
|
-
|
|
32
|
-
|
|
29
|
+
Slots are found by looking for elements with the `adunit` class. The element is required to have a
|
|
30
|
+
`data-format="YOUR_FORMAT"` attribute set on the element to know which format needs to be fetched.
|
|
31
|
+
|
|
32
|
+
Example DOM slots:
|
|
33
|
+
```html
|
|
34
|
+
<div class="adunit" data-format="billboard"></div>
|
|
33
35
|
|
|
34
|
-
### Building
|
|
35
|
-
Build all packages:
|
|
36
|
-
```bash
|
|
37
|
-
npm run build
|
|
38
36
|
```
|
|
39
37
|
|
|
40
|
-
|
|
38
|
+
### Fetching slots before DOM is ready
|
|
39
|
+
If you want to fetch slots before the DOM is ready, you can pass the `initialSlots` option to the `createAdhese`
|
|
40
|
+
function. This is particularly useful if you want to start the fetching process as soon as possible. Downside is that
|
|
41
|
+
you need to know which slots are going to be on the page on beforehand.
|
|
41
42
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
43
|
+
```js
|
|
44
|
+
const adhese = createAdhese({
|
|
45
|
+
account: 'your-account-id',
|
|
46
|
+
initialSlots: [
|
|
47
|
+
{
|
|
48
|
+
containingElement: 'slot-1', // ID of the element that contains the slot
|
|
49
|
+
format: 'billboard',
|
|
50
|
+
},
|
|
51
|
+
{
|
|
52
|
+
containingElement: 'slot-2', // ID of the element that contains the slot
|
|
53
|
+
format: 'leaderboard',
|
|
54
|
+
},
|
|
55
|
+
],
|
|
56
|
+
});
|
|
46
57
|
```
|
|
47
58
|
|
|
48
|
-
|
|
59
|
+
Example HTML:
|
|
60
|
+
```html
|
|
61
|
+
<div id="slot-1" class="adunit" data-format="billboard"></div>
|
|
62
|
+
<div id="slot-2" class="adunit" data-format="leaderboard"></div>
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Options
|
|
66
|
+
The `createAdhese` function accepts the following options:
|
|
67
|
+
|
|
68
|
+
| Option | Type | Default | Description |
|
|
69
|
+
|-----------------------|---------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
70
|
+
| `account`<sup>*</sup> | `string` | - | Your Adhese account ID |
|
|
71
|
+
| `host` | `string` | <code>'https://ads-<span v-pre>{{account}}</span>.adhese.com'</code> | The Adhese API host |
|
|
72
|
+
| `poolHost` | `string` | <code>'https://pool-<span v-pre>{{account}}</span>.adhese.com'</code> | The Adhese pool host |
|
|
73
|
+
| `location` | `string` | `window.location.pathname` | The page location. This is used to determine the current page location identifier. |
|
|
74
|
+
| `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. |
|
|
75
|
+
| `debug` | `boolean` | `false` | Enable debug mode |
|
|
76
|
+
| `findDomSlotsOnLoad` | `boolean` | `false` | Automatically find slots on the page and load them |
|
|
77
|
+
| `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. |
|
|
78
|
+
| `consent` | `boolean` | `false` | User consent for tracking |
|
|
79
|
+
| `initialSlots` | `Array<Slot>` | `[]` | Slots to fetch before the DOM is ready |
|
|
80
|
+
| `logReferrer` | `boolean` | `true` | Will log the `document.referrer` to the Adhese API in a `BASE64` string with the `re` parameter. |
|
|
81
|
+
| `logUrl` | `boolean` | `true` | Will log the `location.href` to the Adhese API in a `BASE64` string with the `ur` parameter. |'
|
|
82
|
+
| `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. |
|
|
83
|
+
| `queries` | `Record<string, string>` | `{mobile: '(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. |
|
|
84
|
+
| `safeframe` | `boolean` | `false` | Enable Safeframe rendering. See [Safeframe usage](/safeframe) for details |
|
|
85
|
+
| `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. |
|
|
49
86
|
|
|
50
|
-
|
|
51
|
-
When installing new dependencies, consider the following:
|
|
52
|
-
- Do I need this dependency in all packages?
|
|
53
|
-
- If yes, install it in the root of the project using `npm install <package>`.
|
|
54
|
-
- If no, install it in the package that needs it using `npm install <package> -w <package-name>`.
|
|
55
|
-
- Is it a dev dependency?
|
|
56
|
-
- If no, make sure to separately install into the `packages/sdk/package.json` to make sure that the dependency is not
|
|
57
|
-
included in the bundle as NPM will handle the dependency.
|
|
87
|
+
\* Required
|