@dreamsengine/dreams-ad-engine 0.1.5 → 0.2.0

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 +50 -2
  2. package/README.md +457 -161
  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 -60
package/README.md CHANGED
@@ -1,237 +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
8
15
 
9
- ### Script
16
+ ## Installation
10
17
 
11
- Add the script of gpt in the template head of html
18
+ ```bash
19
+ # npm
20
+ npm install @dreamsengine/dreams-ad-engine
12
21
 
22
+ # pnpm
23
+ pnpm add @dreamsengine/dreams-ad-engine
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
- refresh
46
- enableTitle
47
- title="Anuncio"
48
- apstag
49
- pubId="xxx-xxxxx-xxxx-xxxx-xxx"
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"}]'
50
79
  ></dreams-ad-engine>
51
80
  ```
52
81
 
53
- ### Options
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
+ ```
54
112
 
55
- | Option | Type | Required | Default |
56
- | ----------- | ------- | -------- | ---------- |
57
- | networkId | String | Yes | - |
58
- | adUnit | String | Yes | - |
59
- | mapping | Array | Yes | - |
60
- | sizing | Array | Yes | - |
61
- | refresh | Boolean | No | false |
62
- | enableTitle | Boolean | No | false |
63
- | title | String | No | Publicidad |
64
- | apstag | Boolean | No | false |
65
- | pubId | String | No | - |
66
- | bidTimeout | Number | No | 2e3 |
113
+ ### Configuration Methods
67
114
 
68
- - refresh: If you use this param the ad will be available to refresh it
69
- - enableTitle: If you use this param one title appears above of the ad
70
- - title: If you use this param overwrite "Publicidad"
71
- - apstag: If you use the apstag of amazon
72
- - pubId: pubID of Amazon
73
- - bidTimeout: Timeout of to init apstag, this value can be in milliseconds or in expression example "2e3"
115
+ ```typescript
116
+ // Check if initialized
117
+ DreamsAdConfig.isInitialized(): boolean
74
118
 
75
- ## Examples
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
76
125
 
77
- Use the library in
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
78
131
 
79
- ### Nextjs 14.2.1 or higher
132
+ // Register custom slots at runtime
133
+ DreamsAdConfig.registerSlot(name: string, config: SlotConfig): void
80
134
 
135
+ // Reset configuration (useful for testing)
136
+ DreamsAdConfig.reset(): void
81
137
  ```
82
- 'use client'
83
- import "@dreamsengine/dreams-ad-engine/dist/dreams-ad-engine"
84
138
 
85
- const AdTestComponent = () => {
86
- return(
87
- <dreams-ad-engine
88
- networkId="xxx"
89
- adUnit="xxx-xx-x-xx"
90
- 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]]}]'
91
- sizing="[[320,50],[320,100],[728,90],[970,90],[920,250],[970,250]]"
92
- ></dreams-ad-engine>
93
- );
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
+ },
94
181
  };
182
+ ```
183
+
184
+ ### Automatic Usage
95
185
 
96
- export default AdTestComponent;
186
+ Simply add `auto-targeting` to your component:
187
+
188
+ ```html
189
+ <dreams-ad-engine slot="top-1" auto-targeting></dreams-ad-engine>
97
190
  ```
98
191
 
99
- 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
100
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();
101
213
  ```
102
- import dynamic from "next/dynamic";
103
214
 
104
- const AdComponentDynamic = dynamic(() => import("./Home/AdComponentHome"), {
105
- 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")
106
224
  });
225
+ ```
107
226
 
108
- const Home = () => {
109
- return (
110
- <main>
111
- <AdComponentDynamic />
112
- </main>
113
- );
114
- };
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
115
281
 
116
- export default Home;
282
+ ### Next.js (App Router)
283
+
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
+ }
117
306
  ```
118
307
 
119
- 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";
120
312
 
313
+ export default function Ad({ slot }: { slot: string }) {
314
+ return <dreams-ad-engine slot={slot} auto-targeting enable-lazy-load />;
315
+ }
121
316
  ```
122
- declare namespace JSX {
123
- interface IntrinsicElements {
124
- "dreams-ad-engine": unknown;
125
- }
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
+ );
126
332
  }
127
333
  ```
128
334
 
129
335
  ### React
130
336
 
131
- ```
132
- import "@dreamsengine/dreams-ad-engine/dist/dreams-ad-engine";
337
+ ```tsx
338
+ import { useEffect } from "react";
339
+ import { DreamsAdConfig } from "@dreamsengine/dreams-ad-engine";
133
340
 
134
341
  function App() {
135
- return (
136
- <>
137
- <dreams-ad-engine
138
- networkId="xxxxx"
139
- adUnit="xxx-xx-x-xx"
140
- 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]]}]'
141
- sizing="[[320,50],[320,100],[728,90],[970,90],[920,250],[970,250]]"
142
- ></dreams-ad-engine>
143
- </>
144
- );
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
+ );
145
357
  }
146
-
147
- export default App;
148
358
  ```
149
359
 
150
- 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>
151
382
 
383
+ <template>
384
+ <dreams-ad-engine :slot="slot" auto-targeting />
385
+ </template>
152
386
  ```
153
- declare namespace JSX {
154
- interface IntrinsicElements {
155
- "dreams-ad-engine": unknown;
156
- }
157
- }
387
+
388
+ ```vue
389
+ <!-- Usage in Nuxt -->
390
+ <template>
391
+ <ClientOnly>
392
+ <Ad slot="top-1" />
393
+ </ClientOnly>
394
+ </template>
158
395
  ```
159
396
 
160
397
  ### Qwik
161
398
 
162
- ```
163
- import { component$ } from "@builder.io/qwik";
399
+ ```tsx
400
+ import { component$, useOnDocument, $ } from "@builder.io/qwik";
401
+ import { DreamsAdConfig } from "@dreamsengine/dreams-ad-engine";
164
402
 
165
403
  export default component$(() => {
166
- return (
167
- <>
168
- <dreams-ad-engine
169
- networkId="xxxxxxxx"
170
- adUnit="xxx-xx-x-xx"
171
- 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]]}]'
172
- sizing="[[320,50],[320,100],[728,90],[970,90],[920,250],[970,250]]"
173
- ></dreams-ad-engine>
174
- </>
175
- );
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 />;
176
416
  });
177
417
  ```
178
418
 
179
- In the fille root add this code
419
+ ---
180
420
 
181
- ```
182
- import { $, component$, useOnDocument } from "@builder.io/qwik";
183
- ...
184
- export default component$(() => {
185
- ...
186
- useOnDocument(
187
- "DOMContentLoaded",
188
- $(() => {
189
- (async () => {
190
- await import(
191
- "@dreamsengine/dreams-ad-engine/dist/dreams-ad-engine"
192
- );
193
- })();
194
- })
195
- );
196
- ...
197
- });
198
- ```
421
+ ## TypeScript Support
199
422
 
200
- 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:
201
424
 
202
- ```
203
- declare module "@dreamsengine/dreams-ad-engine/dist/dreams-ad-engine" {
204
- const AdComponent: any; // Adjust the type if you know the actual type
205
- 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
+ }
206
451
  }
207
452
  ```
208
453
 
209
- ### 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
+ ```
210
468
 
211
- Create a file Ad.vue
469
+ ---
212
470
 
213
- ```
214
- <script setup>
215
- import "@dreamsengine/dreams-ad-engine/dist/dreams-ad-engine";
216
- </script>
471
+ ## Migration from v0.1.x
217
472
 
218
- <template>
219
- <dreams-ad-engine
220
- networkId="xxxxx"
221
- adUnit="xxx-xx-x-xx"
222
- 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]]}]'
223
- sizing="[[320,50],[320,100],[728,90],[970,90],[920,250],[970,250]]"
224
- />
225
- </template>
473
+ Version 0.2.0 is fully backward compatible. Your existing code will continue to work.
226
474
 
475
+ ### Before (v0.1.x)
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
+ />
227
488
  ```
228
489
 
229
- Use this file in between the "ClientOnly"
490
+ ### After (v0.2.0)
230
491
 
492
+ ```tsx
493
+ // Initialize once
494
+ DreamsAdConfig.init({
495
+ networkId: "270959339",
496
+ sitePrefix: "mysite",
497
+ pubId: "amazon-pub-id",
498
+ });
499
+
500
+ // Simple usage everywhere
501
+ <dreams-ad-engine slot="top-1" auto-targeting />
231
502
  ```
232
- ...
233
- <ClientOnly>
234
- <Ad/>
235
- </ClientOnly>
236
- ...
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
+ }
237
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