@dreamsengine/dreams-ad-engine 0.1.6 → 0.2.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.
Files changed (17) hide show
  1. package/CHANGELOG.md +36 -1
  2. package/README.md +465 -182
  3. package/dist/dreams-ad-engine.js +978 -16
  4. package/package.json +11 -1
  5. package/types/features/config/config.provider.d.ts +20 -0
  6. package/types/features/config/config.types.d.ts +22 -0
  7. package/types/features/config/default-mappings.d.ts +2 -0
  8. package/types/features/config/index.d.ts +3 -0
  9. package/types/features/dreamsAdEngine/components/ad.component.d.ts +37 -0
  10. package/types/features/dreamsAdEngine/index.d.ts +1 -0
  11. package/types/features/dreamsAdEngine/types/interfaces.d.ts +50 -0
  12. package/types/features/index.d.ts +3 -0
  13. package/types/features/targeting/index.d.ts +2 -0
  14. package/types/features/targeting/targeting.service.d.ts +12 -0
  15. package/types/features/targeting/targeting.types.d.ts +29 -0
  16. package/types/main.d.ts +1 -0
  17. package/dist/index.html +0 -62
package/README.md CHANGED
@@ -1,250 +1,533 @@
1
- # Usage
1
+ # Dreams Ad Engine
2
2
 
3
- ## NPM
3
+ A lightweight Web Component for Google Ad Manager (GPT) integration with optional Amazon APS header bidding support. Built with [Lit](https://lit.dev/) for maximum compatibility across frameworks.
4
4
 
5
- ```
6
- npm install --save @dreamsengine/dreams-ad-engine
7
- ```
5
+ ## Features
6
+
7
+ - Web Component that works with any framework (React, Next.js, Vue, Nuxt, Qwik, vanilla JS)
8
+ - Google Publisher Tags (GPT) integration
9
+ - Amazon APS header bidding support
10
+ - Responsive ad slots with size mapping
11
+ - Lazy loading support
12
+ - Centralized configuration management
13
+ - Automatic targeting with caching
14
+ - TypeScript support
15
+
16
+ ## Installation
8
17
 
9
- ### Script
18
+ ```bash
19
+ # npm
20
+ npm install @dreamsengine/dreams-ad-engine
10
21
 
11
- Add the script of gpt in the template head of html
22
+ # pnpm
23
+ pnpm add @dreamsengine/dreams-ad-engine
12
24
 
25
+ # yarn
26
+ yarn add @dreamsengine/dreams-ad-engine
13
27
  ```
14
- <html>
15
- <head>
16
- ...
17
- <script async id="gads-js" src="https://securepubads.g.doubleclick.net/tag/js/gpt.js" defer></script>
18
- ...
19
- </head>
20
- ...
21
- </html>
28
+
29
+ ## Required Scripts
30
+
31
+ Add the GPT script to your HTML head:
32
+
33
+ ```html
34
+ <script async src="https://securepubads.g.doubleclick.net/tag/js/gpt.js"></script>
22
35
  ```
23
36
 
24
- Add the script of apstag in the template head of html if you use it.
37
+ If using Amazon APS, also add:
25
38
 
39
+ ```html
40
+ <script async src="https://c.amazon-adsystem.com/aax2/apstag.js"></script>
26
41
  ```
27
- <html>
28
- <head>
29
- ...
30
- <script async id="apstag-js" src="https://c.amazon-adsystem.com/aax2/apstag.js" defer></script>
31
- ...
32
- </head>
33
- ...
34
- </html>
42
+
43
+ ---
44
+
45
+ ## Quick Start
46
+
47
+ ### Option 1: Simple Configuration (Recommended for v0.2.0+)
48
+
49
+ Initialize once in your app entry point, then use slot names throughout:
50
+
51
+ ```typescript
52
+ import { DreamsAdConfig } from "@dreamsengine/dreams-ad-engine";
53
+
54
+ // Initialize once (e.g., in layout.tsx or _app.tsx)
55
+ DreamsAdConfig.init({
56
+ networkId: "270959339",
57
+ sitePrefix: "mysite",
58
+ pubId: "your-amazon-pub-id", // Optional: enables Amazon APS
59
+ });
35
60
  ```
36
61
 
37
- ## Component
62
+ Then use the component with just a slot name:
38
63
 
64
+ ```html
65
+ <dreams-ad-engine slot="top-1" auto-targeting></dreams-ad-engine>
39
66
  ```
67
+
68
+ ### Option 2: Manual Configuration (Backward Compatible)
69
+
70
+ Full control over each ad slot:
71
+
72
+ ```html
40
73
  <dreams-ad-engine
41
- networkId="xxx"
42
- adUnit="xxx-xx-x-xx"
43
- mapping='[{"viewport":[320,0],"sizing":[[320,50],[320,100]]},{"viewport":[720,0],"sizing":[[728,90]]},{"viewport":[970,0],"sizing":[[920,250],[970,90],[728,90]]},{"viewport":[1280,0],"sizing":[[920,250],[970,250],[970,90],[728,90]]}]'
44
- sizing="[[320,50],[320,100],[728,90],[970,90],[920,250],[970,250]]"
45
- targeting='[{"key":"kev1","value": "value1"},{"key":"key2","value":"value2"}...]'
46
- setCentering
47
- enableLazyLoad
48
- configLazyLoad='{"fetchMarginPercent":500,"renderMarginPercent":200,"mobileScaling":2.0}'
49
- refresh
50
- enableTitle
51
- title="Anuncio"
52
- apstag
53
- pubId="xxx-xxxxx-xxxx-xxxx-xxx"
54
- bidTimeout="2e3"
74
+ networkId="270959339"
75
+ adUnit="mysite-is-t-01"
76
+ mapping='[{"viewport":[320,0],"sizing":[[320,50]]}]'
77
+ sizing="[[320,50],[728,90]]"
78
+ targeting='[{"key":"page","value":"home"}]'
55
79
  ></dreams-ad-engine>
56
80
  ```
57
81
 
58
- ### Options
59
-
60
- | Option | Type | Required | Default |
61
- | -------------- | ------- | -------- | ---------------------------------------------------------------------------------- |
62
- | networkId | String | Yes | - |
63
- | adUnit | String | Yes | - |
64
- | mapping | String | Yes | - |
65
- | sizing | String | Yes | - |
66
- | targeting | String | No | \'[]\' |
67
- | setCentering | Boolean | No | false |
68
- | enableLazyLoad | Boolean | No | false |
69
- | configLazyLoad | String | No | \'{\"fetchMarginPercent\":500,\"renderMarginPercent\":200,\"mobileScaling\":2.0}\' |
70
- | refresh | Boolean | No | false |
71
- | enableTitle | Boolean | No | false |
72
- | title | String | No | Publicidad |
73
- | apstag | Boolean | No | false |
74
- | pubId | String | No | - |
75
- | bidTimeout | Number | No | 2e3 |
76
-
77
- - targeting: Array of objects with key and value for targeting
78
- - setCentering: Enables and disables horizontal centering of ads, only ads that are requested after calling this method will be centered
79
- - enableLazyLoad: Enables lazy loading in GPT as defined by the config object.
80
- - configLazyLoad: Config object of LazyLoad
81
- - refresh: If you use this param the ad will be available to refresh it
82
- - enableTitle: If you use this param one title appears above of the ad
83
- - title: If you use this param overwrite "Publicidad"
84
- - apstag: If you use the apstag of amazon
85
- - pubId: pubID of Amazon
86
- - bidTimeout: Timeout of to init apstag, this value can be in milliseconds or in expression example "2e3"
87
-
88
- ## Examples
89
-
90
- Use the library in
91
-
92
- ### Nextjs 14.2.1 or higher
93
-
94
- ```
95
- 'use client'
96
- import "@dreamsengine/dreams-ad-engine/dist/dreams-ad-engine"
97
-
98
- const AdTestComponent = () => {
99
- return(
100
- <dreams-ad-engine
101
- networkId="xxx"
102
- adUnit="xxx-xx-x-xx"
103
- mapping='[{"viewport":[320,0],"sizing":[[320,50],[320,100]]},{"viewport":[720,0],"sizing":[[728,90]]},{"viewport":[970,0],"sizing":[[920,250],[970,90],[728,90]]},{"viewport":[1280,0],"sizing":[[920,250],[970,250],[970,90],[728,90]]}]'
104
- sizing="[[320,50],[320,100],[728,90],[970,90],[920,250],[970,250]]"
105
- ></dreams-ad-engine>
106
- );
82
+ ---
83
+
84
+ ## Configuration Provider
85
+
86
+ The `DreamsAdConfig` class provides centralized configuration management.
87
+
88
+ ### Initialization
89
+
90
+ ```typescript
91
+ import { DreamsAdConfig } from "@dreamsengine/dreams-ad-engine";
92
+
93
+ DreamsAdConfig.init({
94
+ networkId: "270959339", // Required: Google Ad Manager network ID
95
+ sitePrefix: "mysite", // Required: Prefix for ad unit names
96
+ pubId: "amazon-pub-id", // Optional: Amazon APS publisher ID
97
+ bidTimeout: 2000, // Optional: APS bid timeout in ms (default: 2000)
98
+ defaultLazyLoad: { // Optional: Default lazy load settings
99
+ fetchMarginPercent: 500,
100
+ renderMarginPercent: 200,
101
+ mobileScaling: 2.0,
102
+ },
103
+ slots: { // Optional: Custom slot configurations
104
+ "custom-slot": {
105
+ mapping: [{ viewport: [320, 0], sizing: [[300, 250]] }],
106
+ sizing: [[300, 250]],
107
+ position: "box",
108
+ },
109
+ },
110
+ });
111
+ ```
112
+
113
+ ### Configuration Methods
114
+
115
+ ```typescript
116
+ // Check if initialized
117
+ DreamsAdConfig.isInitialized(): boolean
118
+
119
+ // Get configuration values
120
+ DreamsAdConfig.getNetworkId(): string
121
+ DreamsAdConfig.getSitePrefix(): string
122
+ DreamsAdConfig.getPubId(): string | undefined
123
+ DreamsAdConfig.getBidTimeout(): number
124
+ DreamsAdConfig.getDefaultLazyLoad(): LazyLoadConfig
125
+
126
+ // Slot management
127
+ DreamsAdConfig.getSlot(slotName: string): SlotConfig | undefined
128
+ DreamsAdConfig.getSlotMapping(slotName: string): DreamsAdMapping[]
129
+ DreamsAdConfig.getSlotSizing(slotName: string): number[][]
130
+ DreamsAdConfig.buildAdUnit(slotName: string): string
131
+
132
+ // Register custom slots at runtime
133
+ DreamsAdConfig.registerSlot(name: string, config: SlotConfig): void
134
+
135
+ // Reset configuration (useful for testing)
136
+ DreamsAdConfig.reset(): void
137
+ ```
138
+
139
+ ### Built-in Slot Presets
140
+
141
+ The library includes common ad slot configurations:
142
+
143
+ | Slot Name | Position | Common Sizes |
144
+ | -------------- | ------------ | ------------------------------- |
145
+ | `top-1` | top | 320x50, 320x100, 728x90, 970x250 |
146
+ | `top-2` | top | 300x250, 320x50, 728x90, 970x90 |
147
+ | `top-3` | top | 300x250, 320x50, 728x90, 970x90 |
148
+ | `top-4` | top | 300x250, 320x50, 728x90, 970x90 |
149
+ | `top-5` | top | 300x250, 320x50, 728x90 |
150
+ | `box-1` | box | 300x250, 300x600 |
151
+ | `box-2` | box | 300x250, 300x600, 1x1 |
152
+ | `box-3` | box | 300x250, 300x600, 1x1 |
153
+ | `box-4` | box | 300x250, 300x600, 1x1 |
154
+ | `box-5` | box | 300x250, 300x600, 1x1 |
155
+ | `footer` | footer | 320x50, 320x100 |
156
+ | `interstitial` | interstitial | 1x1 |
157
+
158
+ ---
159
+
160
+ ## Targeting Service
161
+
162
+ The `DreamsTargetingService` provides automatic targeting based on page context with caching support.
163
+
164
+ ### How It Works
165
+
166
+ The service polls for a `window.dfp["@context"]` object that your CMS or backend should populate:
167
+
168
+ ```typescript
169
+ // Your CMS/backend should set this on each page
170
+ window.dfp = {
171
+ "@context": {
172
+ postId: "12345",
173
+ catId: "news",
174
+ tagId: "sports,featured",
175
+ typeId: "article",
176
+ dataSection: {
177
+ catName: "News",
178
+ author: "John Doe",
179
+ },
180
+ },
107
181
  };
182
+ ```
108
183
 
109
- export default AdTestComponent;
184
+ ### Automatic Usage
185
+
186
+ Simply add `auto-targeting` to your component:
187
+
188
+ ```html
189
+ <dreams-ad-engine slot="top-1" auto-targeting></dreams-ad-engine>
110
190
  ```
111
191
 
112
- Use the component disabling SSR
192
+ The service will:
193
+ 1. Poll for the DFP context (max 20 retries, 100ms interval)
194
+ 2. Build targeting key-value pairs
195
+ 3. Cache results per URL
196
+ 4. Clear cache on navigation
197
+
198
+ ### Manual Usage
113
199
 
200
+ ```typescript
201
+ import { DreamsTargetingService } from "@dreamsengine/dreams-ad-engine";
202
+
203
+ // Async: wait for context with polling
204
+ const result = await DreamsTargetingService.getTargeting();
205
+ console.log(result.targeting); // Array of { key, value }
206
+ console.log(result.source); // "cache" | "context" | "timeout"
207
+
208
+ // Sync: get cached targeting (returns null if not cached)
209
+ const cached = DreamsTargetingService.getTargetingSync();
210
+
211
+ // Clear cache (e.g., on route change)
212
+ DreamsTargetingService.clearCache();
114
213
  ```
115
- import dynamic from "next/dynamic";
116
214
 
117
- const AdComponentDynamic = dynamic(() => import("./Home/AdComponentHome"), {
118
- ssr: false,
215
+ ### Configuration Options
216
+
217
+ ```typescript
218
+ const result = await DreamsTargetingService.getTargeting({
219
+ contextKey: "@context", // Key in window.dfp (default: "@context")
220
+ maxRetries: 20, // Max polling attempts (default: 20)
221
+ retryInterval: 100, // Ms between retries (default: 100)
222
+ includeUrl: true, // Include URL in targeting (default: true)
223
+ customSegmentFn: "_rl_gen_sg", // Window function for segments (default: "_rl_gen_sg")
119
224
  });
225
+ ```
120
226
 
121
- const Home = () => {
122
- return (
123
- <main>
124
- <AdComponentDynamic />
125
- </main>
126
- );
127
- };
227
+ ### Generated Targeting Keys
228
+
229
+ | Key | Source |
230
+ | -------- | ------------------------------ |
231
+ | url | `window.location.pathname` |
232
+ | catName | `context.dataSection.catName` |
233
+ | postId | `context.postId` |
234
+ | catId | `context.catId` |
235
+ | tag | `context.tagId` |
236
+ | type | `context.typeId` |
237
+ | taxId | `context.taxId` |
238
+ | author | `context.dataSection.author` |
239
+ | _rl | `window._rl_gen_sg()` result |
240
+
241
+ ---
242
+
243
+ ## Component Reference
244
+
245
+ ### Properties
246
+
247
+ | Property | Type | Required | Default | Description |
248
+ | -------------- | ------- | -------- | ----------- | ------------------------------------------ |
249
+ | slot | String | No* | - | Slot name from config (e.g., "top-1") |
250
+ | autoTargeting | Boolean | No | false | Enable automatic targeting |
251
+ | networkId | String | No* | - | Google Ad Manager network ID |
252
+ | adUnit | String | No* | - | Full ad unit name |
253
+ | mapping | String | No* | - | JSON array of viewport/sizing mappings |
254
+ | sizing | String | No* | - | JSON array of ad sizes |
255
+ | targeting | String | No | [] | JSON array of key-value targeting pairs |
256
+ | setCentering | Boolean | No | false | Center ads horizontally |
257
+ | enableLazyLoad | Boolean | No | false | Enable GPT lazy loading |
258
+ | configLazyLoad | String | No | (see below) | JSON lazy load configuration |
259
+ | refresh | Boolean | No | false | Mark slot for refresh capability |
260
+ | enableTitle | Boolean | No | false | Show title above ad |
261
+ | title | String | No | "Publicidad"| Custom title text |
262
+ | apstag | Boolean | No | false | Enable Amazon APS |
263
+ | pubId | String | No | - | Amazon APS publisher ID |
264
+ | bidTimeout | Number | No | 2000 | APS bid timeout in milliseconds |
265
+
266
+ *When using `slot`, the `networkId`, `adUnit`, `mapping`, and `sizing` are automatically resolved from configuration.
267
+
268
+ ### Default Lazy Load Configuration
269
+
270
+ ```json
271
+ {
272
+ "fetchMarginPercent": 500,
273
+ "renderMarginPercent": 200,
274
+ "mobileScaling": 2.0
275
+ }
276
+ ```
277
+
278
+ ---
279
+
280
+ ## Framework Examples
281
+
282
+ ### Next.js (App Router)
128
283
 
129
- export default Home;
284
+ ```tsx
285
+ // app/layout.tsx
286
+ import { DreamsAdConfig } from "@dreamsengine/dreams-ad-engine";
287
+
288
+ // Initialize configuration
289
+ DreamsAdConfig.init({
290
+ networkId: "270959339",
291
+ sitePrefix: "mysite",
292
+ pubId: "amazon-pub-id",
293
+ });
294
+
295
+ export default function RootLayout({ children }) {
296
+ return (
297
+ <html>
298
+ <head>
299
+ <script async src="https://securepubads.g.doubleclick.net/tag/js/gpt.js" />
300
+ <script async src="https://c.amazon-adsystem.com/aax2/apstag.js" />
301
+ </head>
302
+ <body>{children}</body>
303
+ </html>
304
+ );
305
+ }
130
306
  ```
131
307
 
132
- If you use Typescript in the folder src create the file "custom-elements.d.ts" and add the this code.
308
+ ```tsx
309
+ // components/Ad.tsx
310
+ "use client";
311
+ import "@dreamsengine/dreams-ad-engine";
133
312
 
313
+ export default function Ad({ slot }: { slot: string }) {
314
+ return <dreams-ad-engine slot={slot} auto-targeting enable-lazy-load />;
315
+ }
134
316
  ```
135
- declare namespace JSX {
136
- interface IntrinsicElements {
137
- "dreams-ad-engine": unknown;
138
- }
317
+
318
+ ```tsx
319
+ // app/page.tsx
320
+ import dynamic from "next/dynamic";
321
+
322
+ const Ad = dynamic(() => import("@/components/Ad"), { ssr: false });
323
+
324
+ export default function Home() {
325
+ return (
326
+ <main>
327
+ <Ad slot="top-1" />
328
+ <article>...</article>
329
+ <Ad slot="box-1" />
330
+ </main>
331
+ );
139
332
  }
140
333
  ```
141
334
 
142
335
  ### React
143
336
 
144
- ```
145
- import "@dreamsengine/dreams-ad-engine/dist/dreams-ad-engine";
337
+ ```tsx
338
+ import { useEffect } from "react";
339
+ import { DreamsAdConfig } from "@dreamsengine/dreams-ad-engine";
146
340
 
147
341
  function App() {
148
- return (
149
- <>
150
- <dreams-ad-engine
151
- networkId="xxxxx"
152
- adUnit="xxx-xx-x-xx"
153
- mapping='[{"viewport":[320,0],"sizing":[[320,50],[320,100]]},{"viewport":[720,0],"sizing":[[728,90]]},{"viewport":[970,0],"sizing":[[920,250],[970,90],[728,90]]},{"viewport":[1280,0],"sizing":[[920,250],[970,250],[970,90],[728,90]]}]'
154
- sizing="[[320,50],[320,100],[728,90],[970,90],[920,250],[970,250]]"
155
- ></dreams-ad-engine>
156
- </>
157
- );
342
+ useEffect(() => {
343
+ DreamsAdConfig.init({
344
+ networkId: "270959339",
345
+ sitePrefix: "mysite",
346
+ });
347
+
348
+ // Import component
349
+ import("@dreamsengine/dreams-ad-engine");
350
+ }, []);
351
+
352
+ return (
353
+ <div>
354
+ <dreams-ad-engine slot="top-1" auto-targeting />
355
+ </div>
356
+ );
158
357
  }
159
-
160
- export default App;
161
358
  ```
162
359
 
163
- If you use Typescript in the folder src create the file "custom-elements.d.ts" and add the this code.
360
+ ### Vue / Nuxt
361
+
362
+ ```vue
363
+ <!-- components/Ad.vue -->
364
+ <script setup>
365
+ import { onMounted } from "vue";
366
+ import { DreamsAdConfig } from "@dreamsengine/dreams-ad-engine";
367
+
368
+ const props = defineProps({
369
+ slot: { type: String, required: true },
370
+ });
371
+
372
+ onMounted(async () => {
373
+ if (!DreamsAdConfig.isInitialized()) {
374
+ DreamsAdConfig.init({
375
+ networkId: "270959339",
376
+ sitePrefix: "mysite",
377
+ });
378
+ }
379
+ await import("@dreamsengine/dreams-ad-engine");
380
+ });
381
+ </script>
164
382
 
383
+ <template>
384
+ <dreams-ad-engine :slot="slot" auto-targeting />
385
+ </template>
165
386
  ```
166
- declare namespace JSX {
167
- interface IntrinsicElements {
168
- "dreams-ad-engine": unknown;
169
- }
170
- }
387
+
388
+ ```vue
389
+ <!-- Usage in Nuxt -->
390
+ <template>
391
+ <ClientOnly>
392
+ <Ad slot="top-1" />
393
+ </ClientOnly>
394
+ </template>
171
395
  ```
172
396
 
173
397
  ### Qwik
174
398
 
175
- ```
176
- import { component$ } from "@builder.io/qwik";
399
+ ```tsx
400
+ import { component$, useOnDocument, $ } from "@builder.io/qwik";
401
+ import { DreamsAdConfig } from "@dreamsengine/dreams-ad-engine";
177
402
 
178
403
  export default component$(() => {
179
- return (
180
- <>
181
- <dreams-ad-engine
182
- networkId="xxxxxxxx"
183
- adUnit="xxx-xx-x-xx"
184
- mapping='[{"viewport":[320,0],"sizing":[[320,50],[320,100]]},{"viewport":[720,0],"sizing":[[728,90]]},{"viewport":[970,0],"sizing":[[920,250],[970,90],[728,90]]},{"viewport":[1280,0],"sizing":[[920,250],[970,250],[970,90],[728,90]]}]'
185
- sizing="[[320,50],[320,100],[728,90],[970,90],[920,250],[970,250]]"
186
- ></dreams-ad-engine>
187
- </>
188
- );
404
+ useOnDocument(
405
+ "DOMContentLoaded",
406
+ $(() => {
407
+ DreamsAdConfig.init({
408
+ networkId: "270959339",
409
+ sitePrefix: "mysite",
410
+ });
411
+ import("@dreamsengine/dreams-ad-engine");
412
+ })
413
+ );
414
+
415
+ return <dreams-ad-engine slot="top-1" auto-targeting />;
189
416
  });
190
417
  ```
191
418
 
192
- In the fille root add this code
419
+ ---
193
420
 
194
- ```
195
- import { $, component$, useOnDocument } from "@builder.io/qwik";
196
- ...
197
- export default component$(() => {
198
- ...
199
- useOnDocument(
200
- "DOMContentLoaded",
201
- $(() => {
202
- (async () => {
203
- await import(
204
- "@dreamsengine/dreams-ad-engine/dist/dreams-ad-engine"
205
- );
206
- })();
207
- })
208
- );
209
- ...
210
- });
211
- ```
421
+ ## TypeScript Support
212
422
 
213
- If you use Typescript in the folder src create the file "dreams-ad-engine.d.ts" and add the this code.
423
+ Create a type declaration file in your project:
214
424
 
215
- ```
216
- declare module "@dreamsengine/dreams-ad-engine/dist/dreams-ad-engine" {
217
- const AdComponent: any; // Adjust the type if you know the actual type
218
- export default AdComponent;
425
+ ```typescript
426
+ // src/custom-elements.d.ts
427
+ declare namespace JSX {
428
+ interface IntrinsicElements {
429
+ "dreams-ad-engine": React.DetailedHTMLProps<
430
+ React.HTMLAttributes<HTMLElement> & {
431
+ slot?: string;
432
+ "auto-targeting"?: boolean;
433
+ networkId?: string;
434
+ adUnit?: string;
435
+ mapping?: string;
436
+ sizing?: string;
437
+ targeting?: string;
438
+ setCentering?: boolean;
439
+ enableLazyLoad?: boolean;
440
+ configLazyLoad?: string;
441
+ refresh?: boolean;
442
+ enableTitle?: boolean;
443
+ title?: string;
444
+ apstag?: boolean;
445
+ pubId?: string;
446
+ bidTimeout?: number;
447
+ },
448
+ HTMLElement
449
+ >;
450
+ }
219
451
  }
220
452
  ```
221
453
 
222
- ### Nuxt
454
+ ### Exported Types
455
+
456
+ ```typescript
457
+ import type {
458
+ DreamsAdMapping,
459
+ DreamsAdTargeting,
460
+ DFPContext,
461
+ TargetingOptions,
462
+ TargetingResult,
463
+ AdConfigInit,
464
+ LazyLoadConfig,
465
+ SlotConfig,
466
+ } from "@dreamsengine/dreams-ad-engine";
467
+ ```
223
468
 
224
- Create a file Ad.vue
469
+ ---
225
470
 
226
- ```
227
- <script setup>
228
- import "@dreamsengine/dreams-ad-engine/dist/dreams-ad-engine";
229
- </script>
471
+ ## Migration from v0.1.x
230
472
 
231
- <template>
232
- <dreams-ad-engine
233
- networkId="xxxxx"
234
- adUnit="xxx-xx-x-xx"
235
- mapping='[{"viewport":[320,0],"sizing":[[320,50],[320,100]]},{"viewport":[720,0],"sizing":[[728,90]]},{"viewport":[970,0],"sizing":[[920,250],[970,90],[728,90]]},{"viewport":[1280,0],"sizing":[[920,250],[970,250],[970,90],[728,90]]}]'
236
- sizing="[[320,50],[320,100],[728,90],[970,90],[920,250],[970,250]]"
237
- />
238
- </template>
473
+ Version 0.2.0 is fully backward compatible. Your existing code will continue to work.
474
+
475
+ ### Before (v0.1.x)
239
476
 
477
+ ```tsx
478
+ // Manual configuration on every component
479
+ <dreams-ad-engine
480
+ networkId="270959339"
481
+ adUnit="mysite-is-t-01"
482
+ mapping='[{"viewport":[320,0],"sizing":[[320,50],[320,100]]},...]'
483
+ sizing="[[320,50],[320,100],[728,90],...]"
484
+ targeting='[{"key":"url","value":"/home"},...]'
485
+ apstag
486
+ pubId="amazon-pub-id"
487
+ />
240
488
  ```
241
489
 
242
- Use this file in between the "ClientOnly"
490
+ ### After (v0.2.0)
491
+
492
+ ```tsx
493
+ // Initialize once
494
+ DreamsAdConfig.init({
495
+ networkId: "270959339",
496
+ sitePrefix: "mysite",
497
+ pubId: "amazon-pub-id",
498
+ });
243
499
 
500
+ // Simple usage everywhere
501
+ <dreams-ad-engine slot="top-1" auto-targeting />
244
502
  ```
245
- ...
246
- <ClientOnly>
247
- <Ad/>
248
- </ClientOnly>
249
- ...
503
+
504
+ ### Migration Steps
505
+
506
+ 1. Install v0.2.0: `pnpm add @dreamsengine/dreams-ad-engine@latest`
507
+ 2. Add `DreamsAdConfig.init()` to your app entry point
508
+ 3. Optionally replace manual props with `slot` and `auto-targeting`
509
+ 4. Set up `window.dfp["@context"]` in your CMS/backend for auto-targeting
510
+
511
+ ---
512
+
513
+ ## Refreshing Ads
514
+
515
+ To refresh ads marked with `refresh`:
516
+
517
+ ```typescript
518
+ // Access the global slots array
519
+ if (window.dreamsSlotsToUpdate?.length) {
520
+ window.googletag.pubads().refresh(window.dreamsSlotsToUpdate);
521
+ }
250
522
  ```
523
+
524
+ ---
525
+
526
+ ## Browser Support
527
+
528
+ - Chrome, Edge, Firefox, Safari (latest 2 versions)
529
+ - Requires ES2020+ support (async/await, optional chaining)
530
+
531
+ ## License
532
+
533
+ GPL-3.0