@pixeasy/customizer-stage 0.0.45 → 0.0.47
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 +7 -1
- package/docs/personalized-template-integration.md +166 -0
- package/index.d.ts +18 -0
- package/package.json +2 -1
- package/pixeasy-customizer.min.js +246 -245
package/README.md
CHANGED
|
@@ -361,6 +361,8 @@ export default {
|
|
|
361
361
|
|
|
362
362
|
### Personalized Design Templates
|
|
363
363
|
|
|
364
|
+
For a complete third-party integration guide, including save-event payloads and the server webhook, see [Personalized template integration](docs/personalized-template-integration.md).
|
|
365
|
+
|
|
364
366
|
The same npm package also registers `<pixeasy-personalized-customizer>`. This is a separate
|
|
365
367
|
runtime from `<pixeasy-customizer>`: it loads the latest active published template assigned to
|
|
366
368
|
the requested 2D product. Existing `createPixeasyBuilder()` integrations keep their behavior.
|
|
@@ -423,7 +425,8 @@ personalizer.open({
|
|
|
423
425
|
```
|
|
424
426
|
|
|
425
427
|
The SDK loads the exact published template version used by the design and restores its values
|
|
426
|
-
and image transforms.
|
|
428
|
+
and image transforms. Saving again currently creates a new submission with a new design ID,
|
|
429
|
+
submission number, and edit token; store the latest credentials from the event.
|
|
427
430
|
`GET /public/personalized-designs/{designId}` requires the distributor API key and
|
|
428
431
|
`X-Edit-Token` header; it can refresh expired export links.
|
|
429
432
|
|
|
@@ -476,6 +479,9 @@ The custom element also accepts `api-key`, `product-id`, `template-id`, optional
|
|
|
476
479
|
attributes. The builder exposes `getDesignState()`, `getCanvasSvg()`, `getCanvasImage()`,
|
|
477
480
|
and `close()`. The canvas export methods return the current product view with the design
|
|
478
481
|
as SVG or a PNG data URL after rendering is ready; they return `null` before that.
|
|
482
|
+
The builders pass `apiKey` and `editToken` without adding DOM attributes. Existing
|
|
483
|
+
custom-element attributes remain supported and are removed when the element connects.
|
|
484
|
+
The browser still uses the API key in requests, so this only removes it from the DOM.
|
|
479
485
|
`personalized:changed`
|
|
480
486
|
fires as text or images change, `personalized:applied` fires after the design has been saved,
|
|
481
487
|
and `personalized:error` reports loading failures. The design state contains template
|
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
# Personalized template integration
|
|
2
|
+
|
|
3
|
+
This guide is for a storefront or order system embedding the Pixeasy personalized template editor. It covers the browser SDK events, the result of **Save Design**, reopening a saved design, and the separate server webhook. The personalized editor is available through `@pixeasy/customizer-stage` (use the package name supplied for your environment).
|
|
4
|
+
|
|
5
|
+
## Before you start
|
|
6
|
+
|
|
7
|
+
Obtain a distributor API key with `ProductRead`, `SubmissionCreate`, and `SubmissionRead` scopes, an active published personalized template, and a 2D product assigned to that template. Allow your storefront origin for the distributor API key. For server callbacks, configure the distributor's webhook URL and delay in Pixeasy; webhook delivery requires a reachable HTTPS endpoint that accepts JSON POST requests.
|
|
8
|
+
|
|
9
|
+
The SDK loads the published template at `GET /public/products/{productId}/personalized-design-templates/{templateId}` and the selected product details at `GET /public/products/{productId}/personalized-design-templates/{templateId}/product`, using `X-API-Key`. The `productId` passed to `open()` must be one of the template's enabled products. The shopper can then change products and variants offered by that template.
|
|
10
|
+
|
|
11
|
+
## Embed the editor
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npm install @pixeasy/customizer-stage
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
```html
|
|
18
|
+
<div id="personalizer-canvas"></div>
|
|
19
|
+
<div id="personalizer-controls"></div>
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
```ts
|
|
23
|
+
import {
|
|
24
|
+
createPixeasyPersonalizedBuilder,
|
|
25
|
+
PERSONALIZED_CUSTOMIZER_EVENTS,
|
|
26
|
+
} from '@pixeasy/customizer-stage';
|
|
27
|
+
import '@pixeasy/customizer-stage/styles.css';
|
|
28
|
+
|
|
29
|
+
const editor = createPixeasyPersonalizedBuilder();
|
|
30
|
+
|
|
31
|
+
editor.on(PERSONALIZED_CUSTOMIZER_EVENTS.READY, ({ productId, templateId, version }) => {
|
|
32
|
+
console.log('Template ready', productId, templateId, version);
|
|
33
|
+
});
|
|
34
|
+
|
|
35
|
+
editor.on(PERSONALIZED_CUSTOMIZER_EVENTS.CHANGED, (state) => {
|
|
36
|
+
console.log('Selected product and variant', state.productId, state.variantId);
|
|
37
|
+
});
|
|
38
|
+
|
|
39
|
+
editor.on(PERSONALIZED_CUSTOMIZER_EVENTS.APPLIED, async (saved) => {
|
|
40
|
+
// Send this result to your own backend and associate it with the customer/order.
|
|
41
|
+
await fetch('/api/orders/current/personalized-design', {
|
|
42
|
+
method: 'POST',
|
|
43
|
+
headers: { 'Content-Type': 'application/json' },
|
|
44
|
+
body: JSON.stringify({
|
|
45
|
+
designId: saved.designId,
|
|
46
|
+
editToken: saved.editToken,
|
|
47
|
+
revision: saved.revision,
|
|
48
|
+
submissionNumber: saved.submissionNumber,
|
|
49
|
+
productId: saved.state.productId,
|
|
50
|
+
variantId: saved.state.variantId,
|
|
51
|
+
}),
|
|
52
|
+
});
|
|
53
|
+
});
|
|
54
|
+
|
|
55
|
+
editor.on(PERSONALIZED_CUSTOMIZER_EVENTS.ERROR, ({ message }) => {
|
|
56
|
+
console.error('Editor could not load', message);
|
|
57
|
+
});
|
|
58
|
+
|
|
59
|
+
editor.open({
|
|
60
|
+
container: 'personalizer-controls',
|
|
61
|
+
canvasContainerId: 'personalizer-canvas', // Optional; omit to keep the canvas inside the controls.
|
|
62
|
+
apiKey: 'dk_xxx_yyy',
|
|
63
|
+
userUniqueId: 'your-customer-id', // Optional; enables the customer's logo library.
|
|
64
|
+
productId: 'product-uuid',
|
|
65
|
+
templateId: 'template-uuid',
|
|
66
|
+
});
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
`container` accepts an element ID or an `HTMLElement`; `canvasContainerId` is an element ID. Both elements must already exist and must be different. Optional `className` adds a class to the custom element. Optional `readonly` disables editing. Call `editor.close()` on unmount. `getDesignState()` returns the current state or `null` before initialization; `getCanvasSvg()` and `getCanvasImage()` return the current view or `null` before rendering. The canvas image is a PNG data URL.
|
|
70
|
+
|
|
71
|
+
You can also use the registered `<pixeasy-personalized-customizer>` element directly. Set `api-key`, `product-id`, and `template-id`; optional attributes include `user-unique-id`, `canvas-container-id`, `design-id`, `edit-token`, `submission-number`, and `readonly`. Listen for the same event names with `addEventListener`; their payload is in `CustomEvent.detail`. Events bubble and cross the element's shadow boundary.
|
|
72
|
+
|
|
73
|
+
## Browser events
|
|
74
|
+
|
|
75
|
+
| Event | When | `detail` / builder callback argument |
|
|
76
|
+
| --- | --- | --- |
|
|
77
|
+
| `personalized:ready` | The published template and product have loaded. | `{ productId, templateId, version }` |
|
|
78
|
+
| `personalized:changed` | An editable value, selected product, or variant changes. | Current `PersonalizedDesignState` (see below). May fire repeatedly. |
|
|
79
|
+
| `personalized:applied` | **Save Design** has persisted successfully. | `PersonalizedAppliedDesign` (see below). Fires on each successful save, including after reopening a design. |
|
|
80
|
+
| `personalized:error` | Editor initialization or loading fails. | `{ message }`. Save failures are shown in the editor; do not rely on this event for save errors. |
|
|
81
|
+
| `personalized:closed` | The builder's `close()` is called. | `undefined`. This is a builder lifecycle event. |
|
|
82
|
+
|
|
83
|
+
`on(event, handler)` registers a handler and `off(event, handler)` removes it. Register handlers before `open()` so the initial ready event is not missed. For a direct custom element, use `event.detail` instead of the builder callback argument.
|
|
84
|
+
|
|
85
|
+
`PersonalizedDesignState` contains `productId`, optional `variantId`, `variantName`, and `variantColorCode`, `templateId`, `version`, `textValues`, `imageValues`, optional `imageNames`, `defaultAssetIds`, `imageOffsets`, `imageScales`, optional `imageAxisScales`, `imageRotations`, `imageCrops`, optional `cropDetails`, and `textStyles`. Keys in these maps are template field keys. Some image values can be data URLs; do not use `personalized:changed` as an order submission or log its full payload. The save event is the point at which a persistent design ID exists.
|
|
86
|
+
|
|
87
|
+
## What Save Design returns
|
|
88
|
+
|
|
89
|
+
The editor validates required text/images, renders the active canvases and product previews, then calls `POST /public/personalized-designs/apply`. The API returns `designId`, `editToken`, `revision`, `submissionNumber`, `variantIdentifier`, `previews`, and `personalizationPlacements`. The SDK then requests `GET /public/personalized-designs/{designId}` with `X-API-Key` and `X-Edit-Token` to add the PDF URL and saved canvas export links. The resulting `personalized:applied` payload has this shape:
|
|
90
|
+
|
|
91
|
+
```ts
|
|
92
|
+
interface PersonalizedAppliedDesign {
|
|
93
|
+
designId: string; // Same ID as the shared design submission / webhook submissionId.
|
|
94
|
+
editToken: string; // Secret required to reopen or retrieve this design.
|
|
95
|
+
revision: number; // Currently 1 for each new saved submission.
|
|
96
|
+
submissionNumber: string; // Human-readable submission reference.
|
|
97
|
+
variantIdentifier: string; // Selected product variant's external identifier.
|
|
98
|
+
previews: Array<{ viewType: string; url: string; width: number; height: number }>;
|
|
99
|
+
personalizationPlacements: Array<{
|
|
100
|
+
placementKey: string;
|
|
101
|
+
type: 'text' | 'logo';
|
|
102
|
+
value: string | null;
|
|
103
|
+
logoUrl: string | null;
|
|
104
|
+
snapshotId?: string | null;
|
|
105
|
+
}>;
|
|
106
|
+
pdfUrl: string;
|
|
107
|
+
canvases: Array<{ canvasKey: string; pngUrl: string; width: number; height: number }>;
|
|
108
|
+
state: PersonalizedDesignState;
|
|
109
|
+
savedState?: PersonalizedDesignState;
|
|
110
|
+
}
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
`previews` are composed product or variant images. `personalizationPlacements` describe saved text/logo placement snapshots. `canvases` are per-canvas PNG exports with pixel dimensions. `state` is the editor state at save time; `savedState`, when present, is the state returned by the follow-up GET after server-side image references have been stored. `pdfUrl` may be empty while background PDF generation is pending. If that follow-up GET fails, save still succeeds and `personalized:applied` still fires: `pdfUrl` is empty, `savedState` is absent, and `canvases[].pngUrl` falls back to a PNG data URL. Preview and export URLs are temporary; fetch or refresh them when needed rather than treating them as permanent file locations.
|
|
114
|
+
|
|
115
|
+
Store `designId`, `editToken`, `revision`, `submissionNumber`, selected product/variant, and your own customer/order reference on **your server**. Treat the edit token as a customer secret. The browser event is for the current shopper session; it is not a server notification. Update your order association with the latest `designId` after every successful save.
|
|
116
|
+
|
|
117
|
+
To reopen a saved design, pass its `designId` and `editToken` to `open()` with the product and template. The SDK restores the exact published template version and saved values. **Saving again currently creates a new submission**, with a new `designId`, `submissionNumber`, and `editToken`; its revision starts at `1`. Keep the new credentials from the latest `personalized:applied` event. The previous submission remains a separate record. `GET /public/personalized-designs/{designId}` with `X-API-Key` and `X-Edit-Token` can refresh export links. `submissionNumber` is also an optional `open()` input for loading an existing submission; use the design ID plus edit token for the editable saved-design flow.
|
|
118
|
+
|
|
119
|
+
## Server webhook
|
|
120
|
+
|
|
121
|
+
Configure the distributor's webhook URL in Pixeasy. When the production PDF is ready, the backend queues a JSON POST to that URL with `event: "design.submission.ready"`. The configured webhook delay applies to the first delivery. For this 2D personalized flow, a production SVG is not required. The webhook is asynchronous and may arrive after the browser save event, after the shopper leaves, or after a retry. A saved design does not guarantee a webhook: PDF processing must complete and a distributor webhook URL must be configured.
|
|
122
|
+
|
|
123
|
+
Example payload (IDs, URLs, and times are illustrative):
|
|
124
|
+
|
|
125
|
+
```json
|
|
126
|
+
{
|
|
127
|
+
"event": "design.submission.ready",
|
|
128
|
+
"submissionId": "11111111-1111-1111-1111-111111111111",
|
|
129
|
+
"submissionNumber": "DS-000123",
|
|
130
|
+
"productId": "22222222-2222-2222-2222-222222222222",
|
|
131
|
+
"selectedVariantId": "33333333-3333-3333-3333-333333333333",
|
|
132
|
+
"variantIdentifier": "BLUE-L",
|
|
133
|
+
"status": "Completed",
|
|
134
|
+
"pdfUrl": "https://files.example/production.pdf",
|
|
135
|
+
"productionSvgUrl": null,
|
|
136
|
+
"previewUrls": ["https://files.example/front.png"],
|
|
137
|
+
"previews": [
|
|
138
|
+
{ "viewType": "Front", "url": "https://files.example/front.png", "width": 1200, "height": 1200 }
|
|
139
|
+
],
|
|
140
|
+
"overlays": [
|
|
141
|
+
{
|
|
142
|
+
"id": "44444444-4444-4444-4444-444444444444",
|
|
143
|
+
"type": "text",
|
|
144
|
+
"placementKey": "front-name",
|
|
145
|
+
"placementName": "Front name",
|
|
146
|
+
"textValue": "Jordan",
|
|
147
|
+
"value": "Jordan",
|
|
148
|
+
"imageUrl": null,
|
|
149
|
+
"logoUrl": null,
|
|
150
|
+
"renderWidth": 2.25,
|
|
151
|
+
"renderHeight": 0.5,
|
|
152
|
+
"designAreaSizeRanges": [],
|
|
153
|
+
"printableWidthInches": 10,
|
|
154
|
+
"printableHeightInches": 12
|
|
155
|
+
}
|
|
156
|
+
],
|
|
157
|
+
"createdAt": "2026-11-18T10:15:30Z",
|
|
158
|
+
"completedAt": "2026-11-18T10:20:14Z"
|
|
159
|
+
}
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
`submissionId` matches the SDK's `designId`; `submissionNumber` also links the two. `previewUrls` is the flat URL list; `previews` adds view type and pixel dimensions. `overlays` contains text and logo snapshots. For text, `textValue` and `value` contain the text. For logo, `imageUrl` and `logoUrl` contain the logo resource URL when available. Each overlay also has `placementKey`, optional `placementName`, optional render dimensions, printable dimensions in inches for 2D placements, and `designAreaSizeRanges` with size range names, sizes, default flag, and printable dimensions. Nullable fields can be `null`; arrays can be empty. `productionSvgUrl` is normally `null` for 2D submissions. Generated download links can expire.
|
|
163
|
+
|
|
164
|
+
Return a 2xx response promptly to acknowledge delivery. Non-2xx responses, timeouts, and transport failures are retried; the default maximum is five attempts with increasing delays. Process by `submissionId` and `event` idempotently because retries may repeat the same payload. The current delivery code sends JSON with `Content-Type: application/json`; it does not attach a webhook signature header. Protect your endpoint using your own network or URL controls as appropriate. A separate test callback uses `event: "design.submission.test"` with `distributorId` and `sentAt`; it does not carry a design.
|
|
165
|
+
|
|
166
|
+
The ready webhook is queued once per submission when a pending, retrying, or successful ready delivery already exists. Since each save currently creates a new submission, an edited and saved design can generate another ready webhook with a new `submissionId`. Use your latest stored design ID to identify the current version for an order. The webhook reports production readiness and artifacts, while the browser event reports the immediate saved design and edit credentials.
|
package/index.d.ts
CHANGED
|
@@ -16,32 +16,48 @@ export interface PixeasyOpenOptions extends SdkElementConfig {
|
|
|
16
16
|
|
|
17
17
|
export interface PersonalizedCustomizerOpenOptions {
|
|
18
18
|
container: string | HTMLElement;
|
|
19
|
+
className?: string;
|
|
19
20
|
canvasContainerId?: string;
|
|
20
21
|
apiKey: string;
|
|
22
|
+
userUniqueId?: string;
|
|
21
23
|
productId: string;
|
|
22
24
|
templateId: string;
|
|
23
25
|
readonly?: boolean;
|
|
24
26
|
designId?: string;
|
|
25
27
|
editToken?: string;
|
|
26
28
|
submissionNumber?: string;
|
|
29
|
+
/** Save button text; defaults to "Save Design". */
|
|
30
|
+
submitLabel?: string;
|
|
31
|
+
/** Save button text while saving; defaults to "Saving design…". */
|
|
32
|
+
submittingLabel?: string;
|
|
33
|
+
/** Hide the built-in save button; the host saves with `submit()` from its own button. */
|
|
34
|
+
hideSubmit?: boolean;
|
|
27
35
|
}
|
|
28
36
|
|
|
29
37
|
export interface PersonalizedAppliedDesign {
|
|
30
38
|
designId: string;
|
|
31
39
|
editToken: string;
|
|
32
40
|
revision: number;
|
|
41
|
+
submissionNumber: string;
|
|
42
|
+
variantIdentifier: string;
|
|
43
|
+
previews: Array<{ viewType: string; url: string; width: number; height: number }>;
|
|
44
|
+
personalizationPlacements: SubmissionPersonalizationPlacementDetail[];
|
|
33
45
|
pdfUrl: string;
|
|
34
46
|
canvases: Array<{ canvasKey: string; pngUrl: string; width: number; height: number }>;
|
|
35
47
|
state: PersonalizedDesignState;
|
|
48
|
+
savedState?: PersonalizedDesignState;
|
|
36
49
|
}
|
|
37
50
|
|
|
38
51
|
export interface PersonalizedDesignState {
|
|
39
52
|
productId: string;
|
|
40
53
|
variantId?: string;
|
|
54
|
+
variantName?: string;
|
|
55
|
+
variantColorCode?: string;
|
|
41
56
|
templateId: string;
|
|
42
57
|
version: number;
|
|
43
58
|
textValues: Record<string, string>;
|
|
44
59
|
imageValues: Record<string, string[]>;
|
|
60
|
+
imageNames?: Record<string, string[]>;
|
|
45
61
|
defaultAssetIds: Record<string, string[]>;
|
|
46
62
|
imageOffsets: Record<string, { x: number; y: number }[]>;
|
|
47
63
|
imageScales: Record<string, number[]>;
|
|
@@ -91,6 +107,8 @@ export class PersonalizedCustomizerBuilder {
|
|
|
91
107
|
getDesignState(): PersonalizedDesignState | null;
|
|
92
108
|
getCanvasSvg(): string | null;
|
|
93
109
|
getCanvasImage(): string | null;
|
|
110
|
+
/** Save the design, as the built-in button does. Resolves true once `personalized:applied` fired. */
|
|
111
|
+
submit(): Promise<boolean>;
|
|
94
112
|
close(emitClosed?: boolean): this;
|
|
95
113
|
}
|
|
96
114
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@pixeasy/customizer-stage",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.47",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"license": "SEE LICENSE IN LICENSE",
|
|
6
6
|
"publishConfig": {
|
|
@@ -27,6 +27,7 @@
|
|
|
27
27
|
"pixeasy-customizer.css",
|
|
28
28
|
"index.d.ts",
|
|
29
29
|
"README.md",
|
|
30
|
+
"docs",
|
|
30
31
|
"LICENSE",
|
|
31
32
|
"assets",
|
|
32
33
|
"media"
|