@widgetic/embed-sdk 2.0.7 โ†’ 2.0.8

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 CHANGED
@@ -1,568 +1,154 @@
1
- # Widgetic Embed SDK v1.0
1
+ # @widgetic/embed-sdk
2
2
 
3
3
  [![npm version](https://img.shields.io/npm/v/@widgetic/embed-sdk.svg)](https://www.npmjs.com/package/@widgetic/embed-sdk)
4
- [![Build Status](https://img.shields.io/github/workflow/status/widgetic/embed-sdk/CI)](https://github.com/widgetic/embed-sdk/actions)
5
4
  [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
6
5
 
7
- Framework-agnostic JavaScript SDK for embedding Widgetic widgets with support for custom elements, iframes, and batch API integration. Works with any framework or vanilla JavaScript.
8
-
9
- ## Features
10
-
11
- ### ๐Ÿš€ **Phase 1: Foundation & Core Architecture**
12
-
13
- - **Auto-initialization** on page load with intelligent DOM scanning
14
- - **Multiple render modes**: Custom Elements, iframes, with automatic fallback
15
- - **Browser compatibility** detection and graceful degradation
16
- - **Instance management** with singleton pattern and global coordination
17
- - **Comprehensive error handling** and recovery mechanisms
18
-
19
- ### ๐Ÿ”ฅ **Phase 2: Advanced API Integration**
20
-
21
- - **Batch API system** with intelligent request deduplication and caching
22
- - **Dynamic module loading** with HTTP/3 support and version management
23
- - **Performance optimization** via lazy loading and dependency resolution
24
- - **TTL-based caching** for compositions and widget metadata
25
-
26
- ## Framework Compatibility
27
-
28
- โœ… **Framework-Agnostic Core**: No framework dependencies in the core SDK
29
- โœ… **Vanilla JavaScript**: Works directly in any HTML page
30
- โœ… **React**: Compatible with all React versions
31
- โœ… **Vue**: Compatible with Vue 2 and Vue 3
32
- โœ… **Angular**: Compatible with all Angular versions
33
- โœ… **Svelte/SvelteKit**: Compatible with Svelte 3, 4, and 5
34
- โœ… **Next.js**: Works with both SSR and client-side rendering
35
- โœ… **Other Frameworks**: Works with any framework that can render HTML
36
-
37
- See `/demo/` directory for framework-specific integration examples.
38
-
39
- ## ๐Ÿงช Testing & Development
40
-
41
- ### External Developer Test Pages
42
-
43
- The SDK includes comprehensive test pages that simulate real-world usage:
44
-
45
- - **[API Key Test](examples/api-key-test.html)** - Simple test page for trying your API key with different CDN sources
46
- - **[External Developer Test](examples/external-dev-test.html)** - Comprehensive test suite covering all SDK features
47
- - **[UMD Build Test](examples/umd-test.html)** - Tests UMD bundle completeness and functionality
48
- - **[Token Provider Examples](examples/token-provider.html)** - Demonstrates different token provider implementations
49
-
50
- These test pages help you:
51
- - Verify your API key works correctly
52
- - Test different installation methods (npm, unpkg, jsDelivr)
53
- - Validate token provider configurations
54
- - Debug widget rendering issues
55
- - Test bundle completeness for UMD builds
56
-
57
- ## ๐Ÿ—๏ธ Layered API Architecture
58
-
59
- The Widgetic SDK provides three distinct API layers to match different use cases and complexity levels:
60
-
61
- ### ๐ŸŸข High-Level API - Declarative & Auto-magical
62
- **Perfect for:** Simple integrations, HTML-first approaches, minimal JavaScript
63
- **Characteristics:** Auto-initialization, convention over configuration, declarative HTML
6
+ Show a published Widgetic widget on your web page with one tag:
64
7
 
65
8
  ```html
66
- <!-- Just add the script and use custom elements -->
67
- <script src="https://unpkg.com/@widgetic/embed-sdk/dist/umd/embed-sdk.js"></script>
68
- <script>
69
- widgeticEmbedSdk.setApiKey('your-api-key');
70
- </script>
71
-
72
- <widgetic-widget composition-id="your-composition-id" width="400" height="300"></widgetic-widget>
73
- ```
74
-
75
- ### ๐Ÿ”ต Mid-Level API - Programmatic with Configuration
76
- **Perfect for:** Framework integrations, custom UIs, controlled rendering
77
- **Characteristics:** Programmatic control, flexible configuration, managed lifecycle
78
-
79
- ```typescript
80
- import { getWidgetRenderer, setTokenProvider, EndpointTokenProvider } from '@widgetic/embed-sdk';
81
-
82
- setTokenProvider(new EndpointTokenProvider({ tokenEndpoint: '/api/token' }));
83
-
84
- const renderer = getWidgetRenderer();
85
- const widget = await renderer.renderWidget({
86
- compositionId: 'your-composition-id',
87
- container: document.getElementById('widget-container'),
88
- width: 400,
89
- height: 300,
90
- onReady: (widget) => console.log('Widget ready:', widget)
91
- });
92
- ```
93
-
94
- ### ๐Ÿ”ด Low-Level API - Full Control & Manual Management
95
- **Perfect for:** Custom implementations, performance optimization, advanced use cases
96
- **Characteristics:** Manual lifecycle management, direct API access, maximum flexibility
97
-
98
- ```typescript
99
- import { getBatchClient, getModuleLoader, getAuthManager } from '@widgetic/embed-sdk';
100
-
101
- const authManager = getAuthManager();
102
- authManager.setApiKey('your-api-key');
103
-
104
- const batchClient = getBatchClient();
105
- const compositions = await batchClient.getCompositions(['comp-1', 'comp-2']);
106
-
107
- const moduleLoader = getModuleLoader();
108
- const module = await moduleLoader.loadModule(widgetData, { version: 'latest' });
9
+ <widgetic composition-id="COMPOSITION_ID" width="800" height="450"></widgetic>
109
10
  ```
110
11
 
111
- ### ๐Ÿ“š Layer Examples and Documentation
12
+ The script that makes the tag work is called the embed script. This package is the same code for projects that bundle their own JavaScript.
112
13
 
113
- - **[Layered API Examples](examples/layered-api-examples.html)** - Interactive examples for all three layers
114
- - **[Layer Comparison Guide](examples/layered-api-examples.html#comparison)** - When to use each layer
115
- - **[Framework Integration Examples](examples/layered-api-examples.html#mid-level)** - React, Vue, Angular examples
14
+ ## Which way should I use it?
116
15
 
117
- You can also import specific layers:
16
+ | You have | Use |
17
+ | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
18
+ | A web page, a CMS or a template where you can add a `<script>` tag | **The script from the Widgetic CDN.** It is the supported way, and it needs no npm. |
19
+ | A project with a bundler (Vite, webpack, Next.js and so on) that you want to keep free of third-party script tags | This package, `@widgetic/embed-sdk`. |
118
20
 
119
- ```typescript
120
- import { HighLevelAPI, MidLevelAPI, LowLevelAPI } from '@widgetic/embed-sdk';
21
+ ## The script from the CDN
121
22
 
122
- // Use only what you need
123
- const { setApiKey, WidgeticWidget } = HighLevelAPI;
124
- const { getWidgetRenderer } = MidLevelAPI;
125
- const { getBatchClient } = LowLevelAPI;
23
+ ```html
24
+ <script src="https://cdn.widgetic.com/sdks/browser/embed-sdk.js?v=6"></script>
25
+ <widgetic
26
+ composition-id="COMPOSITION_ID"
27
+ resize="fill-width"
28
+ width="800"
29
+ height="450"
30
+ autoscale="on"
31
+ adaptive="480"
32
+ embed-target="site"
33
+ ></widgetic>
126
34
  ```
127
35
 
128
- ## Sibling packages
129
-
130
- In this checkout, the SDK consumes the sibling `api-sdk` package through a
131
- link rather than the published registry copy.
36
+ The script finds every `<widgetic>` tag on the page, also the ones that are added later, asks Widgetic for the published composition and shows it inside the tag.
132
37
 
133
- This package consumes sibling `@widgetic/*` checkouts through a link in `node_modules` that
134
- resolves the checkout itself โ€” its built output, not its source.
135
- The link is made by hand rather than through the `@widgetic/dev-tools` dev-alias setup the
136
- adopting apps use, so a sibling edit stays invisible here until that package rebuilds its
137
- `dist/`.
138
- Setup is the install script this package ships: it reinstalls and then links the sibling, so
139
- `node_modules` keeps resolving the checkout rather than the published package.
140
- The dev-alias workflow these packages have not adopted, and the reasons the adopting apps use
141
- it, are described in [the dev-tools README](../dev-tools/README.md).
142
-
143
- `npm run i` is the whole setup here: it reinstalls `node_modules`, then
144
- re-links the `api-sdk` checkout.
145
-
146
- ```sh
147
- npm run i # install, then link the api-sdk checkout
148
- npm run lapisdk # re-link only, after a fresh node_modules
149
- ```
38
+ The CDN copy is published by Widgetic. It comes from the same source as this package, but it is published separately, so it can be a different build from the version you installed.
150
39
 
151
- ## Installation
152
-
153
- ### npm/yarn
40
+ ## This package, for bundlers
154
41
 
155
42
  ```bash
156
43
  npm install @widgetic/embed-sdk
157
- # or
158
- yarn add @widgetic/embed-sdk
159
- ```
160
-
161
- ### CDN
162
-
163
- ```html
164
- <!-- UMD build (recommended for CDN) -->
165
- <script src="https://unpkg.com/@widgetic/embed-sdk@2.0.0/dist/umd/embed-sdk.js"></script>
166
-
167
- <!-- or via jsDelivr -->
168
- <script src="https://cdn.jsdelivr.net/npm/@widgetic/embed-sdk@2.0.0/dist/umd/embed-sdk.js"></script>
169
-
170
- <!-- Latest version (unpkg) -->
171
- <script src="https://unpkg.com/@widgetic/embed-sdk/dist/umd/embed-sdk.js"></script>
172
44
  ```
173
45
 
174
- The UMD build includes all dependencies bundled, so no additional imports are needed.
175
-
176
- ## Quick Start
177
-
178
- ### HTML (Auto-initialization)
179
-
180
- The SDK automatically initializes when the DOM is ready and scans for `<widgetic-widget>` elements:
46
+ ```js
47
+ import { getSDK } from "@widgetic/embed-sdk";
181
48
 
182
- #### UMD (Global Script)
183
-
184
- ```html
185
- <!DOCTYPE html>
186
- <html>
187
- <head>
188
- <title>Widgetic Widget</title>
189
- <!-- Load SDK from CDN -->
190
- <script src="https://unpkg.com/@widgetic/embed-sdk/dist/umd/embed-sdk.js"></script>
191
- </head>
192
- <body>
193
- <!-- Widget element -->
194
- <widgetic-widget
195
- composition-id="your-composition-id"
196
- render-mode="auto"
197
- width="350"
198
- height="200"
199
- resize="fill-width"
200
- ></widgetic-widget>
201
-
202
- <script>
203
- // Configure authentication (choose one method)
204
-
205
- // Method 1: Static API Key (development only)
206
- const provider = new widgeticEmbedSdk.StaticApiKeyProvider('your-api-key');
207
- widgeticEmbedSdk.setTokenProvider(provider);
208
-
209
- // Method 2: Token from your backend (recommended)
210
- const tokenProvider = new widgeticEmbedSdk.EndpointTokenProvider({
211
- tokenEndpoint: '/api/widgetic/token'
212
- });
213
- widgeticEmbedSdk.setTokenProvider(tokenProvider);
214
-
215
- // Method 3: AuthManager with API key (handles token lifecycle)
216
- widgeticEmbedSdk.setApiKey('your-api-key');
217
-
218
- // SDK will auto-initialize and render widgets
219
- </script>
220
- </body>
221
- </html>
49
+ // Loading the package in a browser starts the embed script: it finds the <widgetic> tags and
50
+ // watches for new ones. Calling getSDK() keeps your bundler from dropping the import.
51
+ getSDK();
222
52
  ```
223
53
 
224
- #### ES Modules
225
-
226
- ```html
227
- <!DOCTYPE html>
228
- <html>
229
- <head>
230
- <title>Widgetic Widget</title>
231
- </head>
232
- <body>
233
- <!-- Widget element -->
234
- <widgetic-widget
235
- composition-id="62bldc5lecb2al3f458b4567"
236
- render-mode="auto"
237
- width="350"
238
- height="50"
239
- resize="fill-width"
240
- autoscale="on"
241
- adaptive="414"
242
- >
243
- </widgetic-widget>
244
-
245
- <!-- Import SDK as ES module -->
246
- <script type="module">
247
- import { setTokenProvider, StaticApiKeyProvider, setApiKey } from '@widgetic/embed-sdk';
248
-
249
- // Configure authentication (choose one method)
250
-
251
- // Method 1: Static API Key (development only)
252
- setTokenProvider(new StaticApiKeyProvider('your-api-key'));
253
-
254
- // Method 2: AuthManager with API key (handles token lifecycle)
255
- setApiKey('your-api-key');
256
-
257
- // SDK will auto-initialize and render widgets
258
- </script>
259
- </body>
260
- </html>
261
- ```
262
-
263
-
264
- ### JavaScript/TypeScript
265
-
266
- ```typescript
267
- import { getSDK, EmbedSDK } from "@widgetic/embed-sdk";
268
-
269
- // Get the global SDK instance
270
- const sdk = getSDK();
54
+ Load it in the browser only: it scans the page, and a server has no page.
271
55
 
272
- // Or create a new instance
273
- const customSDK = new EmbedSDK();
56
+ In a React or Next.js project, load it from an effect, so it runs in the browser:
274
57
 
275
- // Initialize and scan for widgets
276
- await sdk.init();
58
+ ```jsx
59
+ "use client";
60
+ import { useEffect } from "react";
277
61
 
278
- // Manually refresh to detect new widgets
279
- await sdk.refresh();
62
+ export function WidgeticEmbed({ compositionId }) {
63
+ useEffect(() => {
64
+ import("@widgetic/embed-sdk").then(({ getSDK }) => getSDK());
65
+ }, []);
280
66
 
281
- // Get widget instances
282
- const instances = sdk.getInstances();
283
- console.log(`Found ${instances.length} widgets`);
284
- ```
285
-
286
- ## Widget Attributes
287
-
288
- | Attribute | Type | Default | Description |
289
- | ---------------- | ------------------------------- | ------------ | -------------------------------------------- |
290
- | `composition-id` | string | **required** | Unique identifier for the widget composition |
291
- | `render-mode` | `auto\|custom-element\|iframe` | `auto` | Rendering method preference |
292
- | `width` | number\|string | `350` | Widget width in pixels |
293
- | `height` | number\|string | `50` | Widget height in pixels |
294
- | `resize` | `fill-width\|fixed\|responsive` | `fixed` | Resize behavior |
295
- | `autoscale` | `on\|off` | `off` | Enable automatic scaling |
296
- | `adaptive` | number | - | Adaptive breakpoint in pixels |
297
-
298
- ## Authentication & Security
299
-
300
- ### Token Provider (Recommended)
301
-
302
- For production applications, use a Token Provider instead of embedding API keys in client-side code:
303
-
304
- ```typescript
305
- import { setTokenProvider, EndpointTokenProvider } from "@widgetic/embed-sdk";
306
-
307
- // Recommended: Fetch tokens from your backend
308
- setTokenProvider(new EndpointTokenProvider({
309
- tokenEndpoint: '/api/widgetic/token',
310
- headers: {
311
- 'Authorization': 'Bearer ' + userJwtToken
312
- }
313
- }));
314
-
315
- // Custom token logic
316
- setTokenProvider(new FunctionTokenProvider(async () => {
317
- const response = await fetch('/api/auth/widgetic-token');
318
- const data = await response.json();
319
- return data.token;
320
- }));
321
- ```
322
-
323
- Your backend endpoint should return:
324
- ```json
325
- {
326
- "token": "your-widgetic-token",
327
- "expires_in": 3600
67
+ return <widgetic composition-id={compositionId} width="800" height="450" />;
328
68
  }
329
69
  ```
330
70
 
331
- ### Short-lived Tokens with AuthManager (Recommended)
332
-
333
- For maximum security, use the AuthManager to automatically handle short-lived token lifecycle:
334
-
335
- ```typescript
336
- import { getAuthManager, setApiKey } from "@widgetic/embed-sdk";
337
-
338
- // Configure with your API key (server-side recommended)
339
- setApiKey('your-api-key');
340
-
341
- // The AuthManager will automatically:
342
- // - Exchange your API key for short-lived JWTs
343
- // - Cache tokens until they expire
344
- // - Refresh tokens automatically
345
- // - Handle token validation
346
-
347
- const authManager = getAuthManager();
348
- // Token management is now handled automatically
349
- ```
350
-
351
- ### Backend Token Exchange Endpoint (Recommended)
352
-
353
- Implement a secure token exchange endpoint in your backend:
354
-
355
- ```javascript
356
- // Express.js example
357
- app.post('/api/widgetic/token', authenticate, async (req, res) => {
358
- try {
359
- const response = await fetch('https://api.widgetic.com/v1/tokens', {
360
- method: 'POST',
361
- headers: {
362
- 'Authorization': `Bearer ${process.env.WIDGETIC_API_KEY}`,
363
- 'Content-Type': 'application/json'
364
- },
365
- body: JSON.stringify({
366
- scope: ['widgets:read', 'compositions:read'],
367
- expiresIn: 3600 // 1 hour
368
- })
369
- });
370
-
371
- const data = await response.json();
372
- res.json({ token: data.token });
373
- } catch (error) {
374
- res.status(500).json({ error: 'Token generation failed' });
375
- }
376
- });
377
- ```
378
-
379
- ### Development with API Keys
380
-
381
- For development only, you can use static API keys:
382
-
383
- ```typescript
384
- import { StaticApiKeyProvider, setTokenProvider } from "@widgetic/embed-sdk";
385
-
386
- // โš ๏ธ Development only - not for production!
387
- setTokenProvider(new StaticApiKeyProvider('your-api-key'));
388
- ```
389
-
390
- ### Security Best Practices
391
-
392
- 1. **Never expose API keys in client-side code** - Use token providers or AuthManager
393
- 2. **Use short-lived tokens** - Tokens should expire within 1-24 hours
394
- 3. **Implement proper scopes** - Limit token permissions to what's needed
395
- 4. **Validate tokens server-side** - Verify tokens in your backend before issuing them
396
- 5. **Use HTTPS** - Always serve your application over HTTPS in production
397
- 6. **Monitor token usage** - Track token generation and usage patterns
398
-
399
- ## API Reference
400
-
401
- ### Core SDK
402
-
403
- ```typescript
404
- import { getSDK, EmbedSDK, config } from "@widgetic/embed-sdk";
405
-
406
- // Global SDK instance
407
- const sdk = getSDK();
408
-
409
- // SDK configuration
410
- config.apiUrl = "https://api.widgetic.com";
411
- config.cdnUrl = "https://cdn.widgetic.com";
412
- config.debug = true;
413
- ```
414
-
415
- ### Batch API Client
71
+ ## The attributes you will use most
416
72
 
417
- ```typescript
418
- import { getBatchClient } from "@widgetic/embed-sdk";
73
+ | Attribute | What it does |
74
+ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
75
+ | `composition-id` | **Required.** The id of the composition to show. |
76
+ | `width`, `height` | The size of the frame in pixels. When they are missing the frame is 400 by 300. |
77
+ | `resize` | How the frame follows its place on the page: `fixed` (the default), `fill-width`, `fill-height`, `fixed-width`, `fixed-height`, `fill` or `allow-scale-down`. |
78
+ | `autoscale` | `on` turns automatic scaling on. Without the attribute, or with `autoscale="false"`, it is off. |
79
+ | `adaptive` | An adaptive breakpoint in pixels. |
419
80
 
420
- const batchClient = getBatchClient();
81
+ The tag has more attributes: `embed-target`, and the ones for an overlay, a pop-up and for when a widget shows (`overlay-*`, `popup-*`, `trigger-*`). They are described in the Widgetic Partner integration guide, page 8, "Embed widgets on your pages".
421
82
 
422
- // Get multiple compositions efficiently
423
- const compositions = await batchClient.getCompositions(["id1", "id2", "id3"]);
83
+ ### Host context, theme, and partner media (host bridge)
424
84
 
425
- // Get widget metadata
426
- const widgets = await batchClient.getWidgets(["widget1", "widget2"]);
427
- ```
428
-
429
- ### Module Loader
430
-
431
- ```typescript
432
- import { getModuleLoader } from "@widgetic/embed-sdk";
433
-
434
- const moduleLoader = getModuleLoader();
435
-
436
- // Load widget module dynamically
437
- const loadedModule = await moduleLoader.loadModule(widgetData, {
438
- version: "latest",
439
- timeout: 10000,
440
- });
441
-
442
- // Preload modules for performance
443
- await moduleLoader.preloadModules(widgetDataList);
444
- ```
445
-
446
- ### Custom Rendering
447
-
448
- ```typescript
449
- import { getWidgetRenderer } from "@widgetic/embed-sdk";
450
-
451
- const renderer = getWidgetRenderer();
452
-
453
- // Render single widget
454
- const rendered = await renderer.renderWidget({
455
- compositionId: "your-composition-id",
456
- renderMode: "custom-element",
457
- container: document.getElementById("widget-container"),
458
- });
459
-
460
- // Batch render multiple widgets
461
- const results = await renderer.renderWidgets(renderOptions);
462
- ```
85
+ Optional attributes on `<widgetic>` are sent to the published frame as a `widgetic:host` message and kept in sync while the widget is visible:
463
86
 
464
- ## Advanced Configuration
87
+ | Attribute | Purpose |
88
+ | --------------- | ------------------------------------------------------------------------------------ |
89
+ | `context` | JSON object (โ‰ค20 keys) stored on entries and returned on reads |
90
+ | `values` | JSON object that pre-fills fields by name |
91
+ | `lang` | BCP 47 language tag (for example `fr`, `pt-BR`) |
92
+ | `dir` | `ltr` or `rtl` |
93
+ | `mode` | `light` or `dark` |
94
+ | `colors` | JSON theme colours (`primary`, `background`, โ€ฆ) |
95
+ | `media-resolver` | HTTPS URL of a partner function that turns stored media addresses into playable URLs |
465
96
 
466
- ### Environment Configuration
97
+ The element fires DOM events (bubbling, composed) that match the frame protocol: `widgetic:ready`, `widgetic:error`, `widgetic:submitted`, `widgetic:resize`, `widgetic:data`, `widgetic:interaction`, `widgetic:form-submit`. Lookup failures use `widgetic:error` with `detail.code` in lower case (`not_found`, `domain_not_allowed`, `device_restricted`, โ€ฆ).
467
98
 
468
- ```typescript
469
- import { config } from "@widgetic/embed-sdk";
99
+ Markers the script writes: `data-widgetic-mounting`, `data-widgetic-mounted`, `data-device-restricted`, `data-widgetic-refused="CODE"`, `data-widgetic-context-invalid`. See `docs/host-contract.md` for the full contract.
470
100
 
471
- // API endpoints
472
- config.apiUrl = "https://your-api.domain.com";
473
- config.cdnUrl = "https://your-cdn.domain.com";
101
+ ### Telemetry and hosts the script may contact
474
102
 
475
- // Performance tuning
476
- config.batchSize = 50;
477
- config.cacheTTL = 300000; // 5 minutes
103
+ For a typical published embed the script talks to:
478
104
 
479
- // Development
480
- config.debug = true;
481
- config.logLevel = "debug";
482
- ```
483
-
484
- ### Custom Error Handling
105
+ | Host | When | What is sent |
106
+ | ------------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------- |
107
+ | `api.widgetic.com` (or your `data-api-url`) | Composition lookup | Composition id, browser origin (CORS); no API key |
108
+ | `cdn.widgetic.com` | Fallback lookup script | Composition id |
109
+ | `api.axiom.co` | Optional performance batch (if keys are baked into a custom build) | Aggregated performance summary (no end-user id by default) |
110
+ | `events.statsigapi.net` | Optional performance batch (if keys are baked into a custom build) | Custom `widget_performance` event with summary payload |
485
111
 
486
- ```typescript
487
- import { log } from "@widgetic/embed-sdk";
112
+ Turn all telemetry calls off with `data-widgetic-telemetry="off"` on the embed script tag, or `window.WidgeticConfig = { telemetry: false }` before the script runs.
488
113
 
489
- // Listen for SDK events
490
- document.addEventListener("widgetic:error", (event) => {
491
- log.error("Widget error:", event.detail);
492
- });
493
-
494
- document.addEventListener("widgetic:initialized", (event) => {
495
- log.info("Widget initialized:", event.detail);
496
- });
497
- ```
114
+ Local development: set `data-api-url="http://localhost:3000"` on the script tag (or `window.WIDGETIC_EMBED_API`); the script no longer hard-codes Render or localhost addresses.
498
115
 
499
- ## Browser Support
116
+ ## Which websites may show a widget
500
117
 
501
- - **Modern browsers**: Chrome 60+, Firefox 60+, Safari 12+, Edge 79+
502
- - **Custom Elements**: Supported natively or via polyfill
503
- - **HTTP/3**: Automatically detected with graceful fallback to HTTP/2
504
- - **ES Modules**: Native support with UMD fallback for older browsers
118
+ The owner of a composition can limit it to a list of websites. A partner sets that list for its customers through the API, from a server (see the integration guide). On a website that is not on the list, the frame stays empty.
505
119
 
506
- ## Performance Features
120
+ ## Never put an API key in a page
507
121
 
508
- - **Intelligent batching**: Groups API requests for optimal performance
509
- - **Request deduplication**: Prevents redundant network calls
510
- - **TTL caching**: Caches compositions and widget data
511
- - **Lazy loading**: Loads widget modules on demand
512
- - **HTTP/3 support**: Uses the latest protocol when available
513
- - **Tree shaking**: Only includes used functionality in bundles
122
+ A published widget needs no key and no token. Everything on a page can be read by anyone who opens it, so a key put there is a key given away.
514
123
 
515
- ## TypeScript Support
516
-
517
- Full TypeScript support with comprehensive type definitions:
518
-
519
- ```typescript
520
- import type {
521
- WidgetConfig,
522
- WidgetInstance,
523
- RenderMode,
524
- CompositionData,
525
- WidgetData,
526
- } from "@widgetic/embed-sdk";
527
- ```
124
+ This package also contains helpers that take an API key or a token (`setApiKey`, `setTokenProvider`). They are for the Widgetic editors that run for a signed-in Widgetic user, not for pages that only show widgets. Do not use them to show a widget.
528
125
 
529
- ## Contributing
126
+ ## Where to read more
530
127
 
531
- 1. Fork the repository
532
- 2. Create a feature branch: `git checkout -b feature/amazing-feature`
533
- 3. Make your changes and add tests
534
- 4. Run the test suite: `npm test`
535
- 5. Commit your changes: `git commit -m 'Add amazing feature'`
536
- 6. Push to the branch: `git push origin feature/amazing-feature`
537
- 7. Open a Pull Request
128
+ - **The Widgetic Partner integration guide** (your Widgetic contact shares it with you): page 8 for everything about embedding, page 4 for the API and its keys.
129
+ - **`@widgetic/api-sdk`** is the package for calling the Widgetic API from your server. It is not part of this package.
538
130
 
539
- ## Development
131
+ ## For people who work on this package
540
132
 
541
133
  ```bash
542
- # Install dependencies
543
- npm install
544
-
545
- # Start development server
546
- npm run dev
547
-
548
- # Build for production
549
- npm run build
550
-
551
- # Run tests
552
- npm test
553
-
554
- # Lint and format
134
+ npm run i # install, then link the sibling api-sdk checkout (see below)
135
+ npm run dev # build and watch
136
+ npm run build # production build (dist/)
137
+ npm test # unit tests (vitest)
138
+ npm run test:e2e # browser tests (playwright)
555
139
  npm run lint
556
- npm run format
557
140
  ```
558
141
 
142
+ In this checkout the SDK consumes the sibling `api-sdk` package through a link in `node_modules` that points at the checkout itself, so an edit in the sibling stays invisible here until that package rebuilds its `dist/`. `npm run i` reinstalls `node_modules` and links the sibling again; `npm run lapisdk` links it again after a fresh `node_modules`. The dev-alias workflow that the adopting apps use, and why, is described in [the dev-tools README](../dev-tools/README.md).
143
+
144
+ Publishing the CDN copy is a separate step (`npm run publish:cdn`, with `--dry-run` to look first). The npm package is published with `npm publish` and runs the build and a check for secrets first (`prepublishOnly`).
145
+
559
146
  ## License
560
147
 
561
148
  MIT ยฉ [Widgetic](https://widgetic.com)
562
149
 
563
150
  ## Support
564
151
 
565
- - ๐Ÿ“ง Email: support@widgetic.com
566
- - ๐Ÿ’ฌ Discord: [Join our community](https://discord.gg/widgetic)
567
- - ๐Ÿ“– Documentation: [docs.widgetic.com](https://docs.widgetic.com)
568
- - ๐Ÿ› Issues: [GitHub Issues](https://github.com/widgetic/embed-sdk/issues)
152
+ - Email: support@widgetic.com
153
+ - Documentation: [docs.widgetic.com](https://docs.widgetic.com)
154
+ - Issues: [GitHub Issues](https://github.com/widgetic/embed-sdk/issues)