@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 +92 -506
- package/dist/browser/chunks/api.js +1 -1
- package/dist/browser/chunks/performance.js +1 -1
- package/dist/browser/chunks/renderers.js +1 -1
- package/dist/esm/chunks/api.js +1 -1
- package/dist/esm/chunks/performance.js +1 -1
- package/dist/esm/chunks/renderers.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 +1 -1
package/README.md
CHANGED
|
@@ -1,568 +1,154 @@
|
|
|
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
|
-
});
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
120
|
-
import { HighLevelAPI, MidLevelAPI, LowLevelAPI } from '@widgetic/embed-sdk';
|
|
21
|
+
## The script from the CDN
|
|
121
22
|
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
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.
|
|
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
|
-
|
|
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
|
-
##
|
|
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
|
-
|
|
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
|
-
|
|
183
|
-
|
|
184
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
276
|
-
|
|
58
|
+
```jsx
|
|
59
|
+
"use client";
|
|
60
|
+
import { useEffect } from "react";
|
|
277
61
|
|
|
278
|
-
|
|
279
|
-
|
|
62
|
+
export function WidgeticEmbed({ compositionId }) {
|
|
63
|
+
useEffect(() => {
|
|
64
|
+
import("@widgetic/embed-sdk").then(({ getSDK }) => getSDK());
|
|
65
|
+
}, []);
|
|
280
66
|
|
|
281
|
-
|
|
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
|
-
|
|
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
|
-
|
|
418
|
-
|
|
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
|
-
|
|
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
|
-
|
|
423
|
-
const compositions = await batchClient.getCompositions(["id1", "id2", "id3"]);
|
|
83
|
+
### Host context, theme, and partner media (host bridge)
|
|
424
84
|
|
|
425
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
476
|
-
config.batchSize = 50;
|
|
477
|
-
config.cacheTTL = 300000; // 5 minutes
|
|
103
|
+
For a typical published embed the script talks to:
|
|
478
104
|
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
116
|
+
## Which websites may show a widget
|
|
500
117
|
|
|
501
|
-
|
|
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
|
-
##
|
|
120
|
+
## Never put an API key in a page
|
|
507
121
|
|
|
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
|
|
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
|
-
|
|
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
|
-
##
|
|
126
|
+
## Where to read more
|
|
530
127
|
|
|
531
|
-
|
|
532
|
-
|
|
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
|
-
##
|
|
131
|
+
## For people who work on this package
|
|
540
132
|
|
|
541
133
|
```bash
|
|
542
|
-
#
|
|
543
|
-
npm
|
|
544
|
-
|
|
545
|
-
#
|
|
546
|
-
npm run
|
|
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
|
-
-
|
|
566
|
-
-
|
|
567
|
-
-
|
|
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)
|