@widgetic/embed-sdk 2.0.7 โ 2.0.9
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 +104 -498
- package/dist/browser/chunks/ABTestManager.js +1 -1
- package/dist/browser/chunks/advanced.js +1 -1
- package/dist/browser/chunks/api.js +1 -1
- package/dist/browser/chunks/core.js +1 -1
- package/dist/browser/chunks/display.js +1 -1
- package/dist/browser/chunks/media.js +1 -1
- package/dist/browser/chunks/messaging.js +1 -1
- package/dist/browser/chunks/performance.js +1 -1
- package/dist/browser/chunks/renderers.js +1 -1
- package/dist/browser/chunks/scanner.js +1 -1
- package/dist/browser/chunks/security.js +1 -1
- package/dist/browser/embed-bootstrap.js +1 -1
- package/dist/browser/embed-sdk.js +1 -1
- package/dist/esm/chunks/ABTestManager.js +1 -1
- package/dist/esm/chunks/advanced.js +1 -1
- package/dist/esm/chunks/api.js +1 -1
- package/dist/esm/chunks/core.js +1 -1
- package/dist/esm/chunks/display.js +1 -1
- package/dist/esm/chunks/media.js +1 -1
- package/dist/esm/chunks/messaging.js +1 -1
- package/dist/esm/chunks/performance.js +1 -1
- package/dist/esm/chunks/renderers.js +1 -1
- package/dist/esm/chunks/scanner.js +1 -1
- package/dist/esm/chunks/security.js +1 -1
- package/dist/esm/embed-bootstrap.js +1 -1
- package/dist/esm/embed-sdk.js +1 -1
- package/dist/esm/types/utils/embed-gateway-codes.d.ts +9 -0
- package/dist/esm/types/utils/embed-telemetry.d.ts +13 -0
- package/dist/esm/types/utils/host-bridge-markers.d.ts +20 -0
- package/dist/esm/types/utils/host-bridge-snapshot.d.ts +18 -0
- package/dist/esm/types/utils/host-bridge-validation.d.ts +19 -0
- package/dist/esm/types/utils/hydrate-published-host.d.ts +4 -7
- package/dist/esm/types/utils/public-embed-lookup.d.ts +16 -6
- package/dist/esm/types/utils/published-host-bridge.d.ts +8 -0
- package/dist/umd/embed-bootstrap.js +1 -1
- package/dist/umd/embed-sdk.js +1 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,568 +1,174 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @widgetic/embed-sdk
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@widgetic/embed-sdk)
|
|
4
|
-
[](https://github.com/widgetic/embed-sdk/actions)
|
|
5
4
|
[](https://www.typescriptlang.org/)
|
|
6
5
|
|
|
7
|
-
|
|
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
|
-
|
|
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
|
-
});
|
|
9
|
+
<widgetic composition-id="COMPOSITION_ID" width="800" height="450"></widgetic>
|
|
92
10
|
```
|
|
93
11
|
|
|
94
|
-
|
|
95
|
-
**Perfect for:** Custom implementations, performance optimization, advanced use cases
|
|
96
|
-
**Characteristics:** Manual lifecycle management, direct API access, maximum flexibility
|
|
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.
|
|
97
13
|
|
|
98
|
-
|
|
99
|
-
import { getBatchClient, getModuleLoader, getAuthManager } from '@widgetic/embed-sdk';
|
|
14
|
+
## Which way should I use it?
|
|
100
15
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
const compositions = await batchClient.getCompositions(['comp-1', 'comp-2']);
|
|
106
|
-
|
|
107
|
-
const moduleLoader = getModuleLoader();
|
|
108
|
-
const module = await moduleLoader.loadModule(widgetData, { version: 'latest' });
|
|
109
|
-
```
|
|
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`. |
|
|
110
20
|
|
|
111
|
-
|
|
21
|
+
## The script from the CDN
|
|
112
22
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
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
|
-
|
|
129
|
-
|
|
130
|
-
In this checkout, the SDK consumes the sibling `api-sdk` package through a
|
|
131
|
-
link rather than the published registry copy.
|
|
132
|
-
|
|
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).
|
|
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.
|
|
142
37
|
|
|
143
|
-
|
|
144
|
-
re-links the `api-sdk` checkout.
|
|
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.
|
|
145
39
|
|
|
146
|
-
|
|
147
|
-
npm run i # install, then link the api-sdk checkout
|
|
148
|
-
npm run lapisdk # re-link only, after a fresh node_modules
|
|
149
|
-
```
|
|
150
|
-
|
|
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
|
-
```
|
|
173
|
-
|
|
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:
|
|
181
|
-
|
|
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>
|
|
222
44
|
```
|
|
223
45
|
|
|
224
|
-
|
|
46
|
+
```js
|
|
47
|
+
import { getSDK } from "@widgetic/embed-sdk";
|
|
225
48
|
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
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>
|
|
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();
|
|
261
52
|
```
|
|
262
53
|
|
|
54
|
+
Load it in the browser only: it scans the page, and a server has no page.
|
|
263
55
|
|
|
264
|
-
|
|
56
|
+
In a React or Next.js project, load it from an effect, so it runs in the browser:
|
|
265
57
|
|
|
266
|
-
```
|
|
267
|
-
|
|
58
|
+
```jsx
|
|
59
|
+
"use client";
|
|
60
|
+
import { useEffect } from "react";
|
|
268
61
|
|
|
269
|
-
|
|
270
|
-
|
|
62
|
+
export function WidgeticEmbed({ compositionId }) {
|
|
63
|
+
useEffect(() => {
|
|
64
|
+
import("@widgetic/embed-sdk").then(({ getSDK }) => getSDK());
|
|
65
|
+
}, []);
|
|
271
66
|
|
|
272
|
-
|
|
273
|
-
const customSDK = new EmbedSDK();
|
|
274
|
-
|
|
275
|
-
// Initialize and scan for widgets
|
|
276
|
-
await sdk.init();
|
|
277
|
-
|
|
278
|
-
// Manually refresh to detect new widgets
|
|
279
|
-
await sdk.refresh();
|
|
280
|
-
|
|
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
|
-
|
|
71
|
+
## The attributes you will use most
|
|
332
72
|
|
|
333
|
-
|
|
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. |
|
|
334
80
|
|
|
335
|
-
|
|
336
|
-
import { getAuthManager, setApiKey } from "@widgetic/embed-sdk";
|
|
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".
|
|
337
82
|
|
|
338
|
-
|
|
339
|
-
setApiKey('your-api-key');
|
|
83
|
+
### Host context, theme, and partner media (host bridge)
|
|
340
84
|
|
|
341
|
-
|
|
342
|
-
// - Exchange your API key for short-lived JWTs
|
|
343
|
-
// - Cache tokens until they expire
|
|
344
|
-
// - Refresh tokens automatically
|
|
345
|
-
// - Handle token validation
|
|
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:
|
|
346
86
|
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
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
|
-
```
|
|
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 |
|
|
378
96
|
|
|
379
|
-
|
|
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`, โฆ).
|
|
380
98
|
|
|
381
|
-
|
|
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.
|
|
382
100
|
|
|
383
|
-
|
|
384
|
-
import { StaticApiKeyProvider, setTokenProvider } from "@widgetic/embed-sdk";
|
|
101
|
+
### Telemetry and hosts the script may contact
|
|
385
102
|
|
|
386
|
-
|
|
387
|
-
setTokenProvider(new StaticApiKeyProvider('your-api-key'));
|
|
388
|
-
```
|
|
103
|
+
For a typical published embed the script talks to:
|
|
389
104
|
|
|
390
|
-
|
|
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 |
|
|
391
111
|
|
|
392
|
-
|
|
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
|
|
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.
|
|
398
113
|
|
|
399
|
-
|
|
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.
|
|
400
115
|
|
|
401
|
-
|
|
116
|
+
## Which websites may show a widget
|
|
402
117
|
|
|
403
|
-
|
|
404
|
-
import { getSDK, EmbedSDK, config } from "@widgetic/embed-sdk";
|
|
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.
|
|
405
119
|
|
|
406
|
-
|
|
407
|
-
const sdk = getSDK();
|
|
120
|
+
## Never put an API key in a page
|
|
408
121
|
|
|
409
|
-
|
|
410
|
-
config.apiUrl = "https://api.widgetic.com";
|
|
411
|
-
config.cdnUrl = "https://cdn.widgetic.com";
|
|
412
|
-
config.debug = true;
|
|
413
|
-
```
|
|
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.
|
|
414
123
|
|
|
415
|
-
|
|
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.
|
|
416
125
|
|
|
417
|
-
|
|
418
|
-
import { getBatchClient } from "@widgetic/embed-sdk";
|
|
126
|
+
## Where to read more
|
|
419
127
|
|
|
420
|
-
|
|
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.
|
|
421
130
|
|
|
422
|
-
|
|
423
|
-
const compositions = await batchClient.getCompositions(["id1", "id2", "id3"]);
|
|
131
|
+
## For people who work on this package
|
|
424
132
|
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
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
|
-
```
|
|
463
|
-
|
|
464
|
-
## Advanced Configuration
|
|
465
|
-
|
|
466
|
-
### Environment Configuration
|
|
467
|
-
|
|
468
|
-
```typescript
|
|
469
|
-
import { config } from "@widgetic/embed-sdk";
|
|
470
|
-
|
|
471
|
-
// API endpoints
|
|
472
|
-
config.apiUrl = "https://your-api.domain.com";
|
|
473
|
-
config.cdnUrl = "https://your-cdn.domain.com";
|
|
474
|
-
|
|
475
|
-
// Performance tuning
|
|
476
|
-
config.batchSize = 50;
|
|
477
|
-
config.cacheTTL = 300000; // 5 minutes
|
|
478
|
-
|
|
479
|
-
// Development
|
|
480
|
-
config.debug = true;
|
|
481
|
-
config.logLevel = "debug";
|
|
482
|
-
```
|
|
483
|
-
|
|
484
|
-
### Custom Error Handling
|
|
485
|
-
|
|
486
|
-
```typescript
|
|
487
|
-
import { log } from "@widgetic/embed-sdk";
|
|
488
|
-
|
|
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
|
-
});
|
|
133
|
+
```bash
|
|
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)
|
|
139
|
+
npm run lint
|
|
497
140
|
```
|
|
498
141
|
|
|
499
|
-
|
|
500
|
-
|
|
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
|
|
505
|
-
|
|
506
|
-
## Performance Features
|
|
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).
|
|
507
143
|
|
|
508
|
-
|
|
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
|
|
144
|
+
## Publishing
|
|
514
145
|
|
|
515
|
-
|
|
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
|
-
```
|
|
146
|
+
GitLab CI on `main` publishes this package and then replaces `https://cdn.widgetic.com/sdks/browser/embed-sdk.js`. The npm job is a Trusted Publisher (`NPM_ID_TOKEN`). It does not use a long-lived token.
|
|
528
147
|
|
|
529
|
-
|
|
148
|
+
1. Bump `version` in `package.json`.
|
|
149
|
+
2. Commit and push `main`.
|
|
150
|
+
3. The `publish` job runs `npm publish` when that version is not already on npm, then uploads `dist/umd/embed-sdk.js` to the CDN and purges the cached copies.
|
|
530
151
|
|
|
531
|
-
|
|
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
|
|
152
|
+
The CDN upload needs six CI/CD variables on this project, protected, environment scope `cdn`: `CLOUDFLARE_PUBLIC_ENDPOINT`, `R2_WIDGETS_NAME`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ZONE_ID`. The last two are what let the job purge the cached file.
|
|
538
153
|
|
|
539
|
-
|
|
154
|
+
When the GitLab job fails with `ci_quota_exceeded`, publish from a laptop. That does not use CI minutes. The group's remaining minutes are at [Usage quotas](https://gitlab.com/groups/widgeticai/-/usage_quotas), on the pipelines tab.
|
|
540
155
|
|
|
541
156
|
```bash
|
|
542
|
-
|
|
543
|
-
npm install
|
|
544
|
-
|
|
545
|
-
# Start development server
|
|
546
|
-
npm run dev
|
|
547
|
-
|
|
548
|
-
# Build for production
|
|
157
|
+
npm ci
|
|
549
158
|
npm run build
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
npm
|
|
553
|
-
|
|
554
|
-
# Lint and format
|
|
555
|
-
npm run lint
|
|
556
|
-
npm run format
|
|
159
|
+
npm publish --access public
|
|
160
|
+
npm run publish:cdn:dry-run
|
|
161
|
+
npm run publish:cdn -- --purge
|
|
557
162
|
```
|
|
558
163
|
|
|
164
|
+
`npm publish` needs the token in `~/.npmrc`. Do not commit that file. The dry run changes nothing. The last command asks you to type `publish`, uploads the file, and purges the cache. Check `npm view @widgetic/embed-sdk version` and the `last-modified` header of `https://cdn.widgetic.com/sdks/browser/embed-sdk.js`. What the upload checks, and how to roll back, is in `__docs/05-advanced/06-publishing-to-cdn.md`.
|
|
165
|
+
|
|
559
166
|
## License
|
|
560
167
|
|
|
561
168
|
MIT ยฉ [Widgetic](https://widgetic.com)
|
|
562
169
|
|
|
563
170
|
## Support
|
|
564
171
|
|
|
565
|
-
-
|
|
566
|
-
-
|
|
567
|
-
-
|
|
568
|
-
- ๐ Issues: [GitHub Issues](https://github.com/widgetic/embed-sdk/issues)
|
|
172
|
+
- Email: support@widgetic.com
|
|
173
|
+
- Documentation: [docs.widgetic.com](https://docs.widgetic.com)
|
|
174
|
+
- Issues: [GitHub Issues](https://github.com/widgetic/embed-sdk/issues)
|