@soyio/soyio-widget 2.15.3 → 2.16.1
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 +362 -179
- package/dist/index.d.ts +23 -1
- package/dist/index.js +131 -128
- package/dist/index.umd.cjs +14 -14
- package/package.json +13 -3
package/README.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
<h1 align="center">Soyio
|
|
1
|
+
<h1 align="center">Soyio Widget</h1>
|
|
2
2
|
|
|
3
3
|
<p align="center">
|
|
4
4
|
<em>
|
|
5
|
-
|
|
5
|
+
Our SDK for web based integrations
|
|
6
6
|
</em>
|
|
7
7
|
</p>
|
|
8
8
|
|
|
@@ -12,6 +12,21 @@
|
|
|
12
12
|
</a>
|
|
13
13
|
</p>
|
|
14
14
|
|
|
15
|
+
## Table of Contents
|
|
16
|
+
|
|
17
|
+
- [Installation](#installation)
|
|
18
|
+
- [Usage](#usage)
|
|
19
|
+
- [Modules](#modules)
|
|
20
|
+
- [Consent Request Box](#consent-request-box)
|
|
21
|
+
- [Privacy Center](#privacy-center)
|
|
22
|
+
- [Disclosure Request](#disclosure-request)
|
|
23
|
+
- [Signature Attempt](#signature-attempt)
|
|
24
|
+
- [Auth Request](#auth-request)
|
|
25
|
+
- [Appearance](#appearance)
|
|
26
|
+
- [TypeScript](#typescript)
|
|
27
|
+
- [Server Side Rendering (SSR)](#server-side-rendering-ssr)
|
|
28
|
+
|
|
29
|
+
|
|
15
30
|
## Installation
|
|
16
31
|
|
|
17
32
|
Install using npm! (or your favorite package manager)
|
|
@@ -22,18 +37,192 @@ npm install @soyio/soyio-widget
|
|
|
22
37
|
|
|
23
38
|
# Using yarn
|
|
24
39
|
yarn add @soyio/soyio-widget
|
|
40
|
+
|
|
41
|
+
# Using pnpm
|
|
42
|
+
pnpm add @soyio/soyio-widget
|
|
25
43
|
```
|
|
26
44
|
|
|
27
45
|
## Usage
|
|
28
46
|
|
|
29
47
|
Integrate the widget into your frontend framework using the script below. Ensure to replace placeholders (e.g., \<request>, \<company id>) with actual values relevant to your implementation.
|
|
30
48
|
|
|
31
|
-
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## Modules
|
|
52
|
+
|
|
53
|
+
The Soyio Widget provides several modules that you can integrate into your application:
|
|
54
|
+
|
|
55
|
+
- **Consent Request Box**: Embed consent requests directly within your webpage
|
|
56
|
+
- **Privacy Center**: Embed the Privacy Center inside your page with customizable features
|
|
57
|
+
- **Disclosure Request**: Verify users and collect required data through validation or authentication
|
|
58
|
+
- **Signature Attempt**: Enable users to digitally sign documents after authentication
|
|
59
|
+
- **Auth Request**: Authenticate users using access keys or facial video
|
|
60
|
+
|
|
61
|
+
## Consent Request Box
|
|
62
|
+
|
|
63
|
+
> 📖 [Integration Guide](https://docs.soyio.id/docs/integration-guide/consent/introduction)
|
|
64
|
+
|
|
65
|
+
The **`ConsentBox`** is a component that allows you to embed a consent request directly within your webpage, rather than opening it in a popup window. This is particularly useful when you want to integrate the consent flow seamlessly into your application's interface.
|
|
66
|
+
|
|
67
|
+
```html
|
|
68
|
+
<!-- Add a container div where the consent request will be mounted -->
|
|
69
|
+
<div id="consent-request-box"></div>
|
|
70
|
+
|
|
71
|
+
<script>
|
|
72
|
+
import { ConsentBox } from "@soyio/soyio-widget";
|
|
73
|
+
|
|
74
|
+
// Configuration for the consent request
|
|
75
|
+
const consentOptions = {
|
|
76
|
+
consentTemplateId: "<consent template id>",
|
|
77
|
+
onEvent: (data) => console.log(data),
|
|
78
|
+
isSandbox: true, // Optional
|
|
79
|
+
appearance: {}, // Optional
|
|
80
|
+
actionToken: "<action token>", // Optional
|
|
81
|
+
entityId: "<entity id>", // Optional
|
|
82
|
+
context: "<context>", // Optional
|
|
83
|
+
onReady: () => console.log("ConsentBox is ready"), // Optional
|
|
84
|
+
optionalReconsentBehavior: "notice", // Optional
|
|
85
|
+
mandatoryReconsentBehavior: "notice", // Optional
|
|
86
|
+
};
|
|
87
|
+
|
|
88
|
+
// Wait for DOM to be fully loaded
|
|
89
|
+
document.addEventListener("DOMContentLoaded", () => {
|
|
90
|
+
// Create and mount the consent request box
|
|
91
|
+
const consentBox = new ConsentBox(consentOptions);
|
|
92
|
+
consentBox.mount("#consent-request-box");
|
|
93
|
+
});
|
|
94
|
+
</script>
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
### Consent Request Box Events
|
|
98
|
+
|
|
99
|
+
The `onEvent` follows the following format:
|
|
100
|
+
|
|
101
|
+
```typescript
|
|
102
|
+
{
|
|
103
|
+
eventName: 'CONSENT_CHECKBOX_CHANGE',
|
|
104
|
+
isSelected: boolean,
|
|
105
|
+
actionToken: string,
|
|
106
|
+
}
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
### Methods
|
|
110
|
+
|
|
111
|
+
- **`getState()`**: Returns the current state of the consent box. The returned object has the following structure:
|
|
112
|
+
|
|
113
|
+
```typescript
|
|
114
|
+
{
|
|
115
|
+
isSelected: boolean,
|
|
116
|
+
actionToken: string | null,
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
### Attribute Descriptions
|
|
122
|
+
|
|
123
|
+
- **`consentTemplateId`**: Identifier of consent template. It must start with `'constpl_'`.
|
|
124
|
+
- **`isSelected`**: Boolean value indicating whether the consent checkbox is selected or not.
|
|
125
|
+
- **`appearance`**: Customize the appearance of the iframe. [Learn more](https://docs.soyio.id/docs/integration-guide/modules/consent).
|
|
126
|
+
- **`actionToken`**: In case of losing the state of the consent (i.e. page reload), you can use a previously generated `actionToken` to restore the state of the consent.
|
|
127
|
+
- **`entityId`**: Identifier of the `entity` associated with a `ConsentAction`. If provided and a consent was previously granted by this entity, the UI will display a message indicating that consent has already been given.
|
|
128
|
+
- **`context`**: Additional information that will be saved with the consent. Useful when you want to track the consent from a specific context.
|
|
129
|
+
- **`onReady`**: Optional callback that executes when the consent box is ready to use. You can use this to handle logic when the iframe is not mounted yet.
|
|
130
|
+
- **`optionalReconsentBehavior`**: What should happen when the consent is initialized with an `entityId` that has already given consent on an optional category.
|
|
131
|
+
- `notice` will show a message letting the user know that they have already given consent,
|
|
132
|
+
- `askAgain` will show the consent as if it wasn't given in the first place,
|
|
133
|
+
- `hide` will not show the consent at all.
|
|
134
|
+
|
|
135
|
+
We strongly recommend using `notice` so the user doesn't have to give the consent again and knows what they have already given consent to.
|
|
136
|
+
- **`mandatoryReconsentBehavior`**: What should happen when the consent is initialized with an `entityId` that has already given consent on a mandatory category.
|
|
137
|
+
- `notice` will show a message letting the user know that they have already given consent,
|
|
138
|
+
- `askAgain` will show the consent as if it wasn't given in the first place,
|
|
139
|
+
|
|
140
|
+
We don't support hiding the mandatory consent, and we strongly recommend using `notice` so the user doesn't have to give the consent again and knows what they have already given consent to.
|
|
141
|
+
|
|
142
|
+
## Privacy Center
|
|
143
|
+
|
|
144
|
+
> 📖 [Integration Guide](https://docs.soyio.id/docs/integration-guide/privacy-center/introduction)
|
|
145
|
+
|
|
146
|
+
The `PrivacyCenterBox` lets you embed the Privacy Center inside your page. You can scope which features to show and which data subjects are relevant to your interface. For more info check [our docs](https://docs.soyio.id/).
|
|
147
|
+
|
|
148
|
+
```html
|
|
149
|
+
<!-- Add a container div where the Privacy Center will be mounted -->
|
|
150
|
+
<div id="privacy-center-box"></div>
|
|
151
|
+
|
|
152
|
+
<script>
|
|
153
|
+
import { PrivacyCenterBox } from "@soyio/soyio-widget";
|
|
154
|
+
|
|
155
|
+
// Configuration for the Privacy Center
|
|
156
|
+
const privacyCenterOptions = {
|
|
157
|
+
// Choose ONE of the following authentication modes:
|
|
158
|
+
// 1) Public mode
|
|
159
|
+
companyId: "<company id>", // e.g. com_...
|
|
160
|
+
|
|
161
|
+
// 2) Authenticated mode
|
|
162
|
+
// sessionToken: "<session token>",
|
|
163
|
+
|
|
164
|
+
// Feature flags (optional)
|
|
165
|
+
enabledFeatures: ["DataSubjectRequest", "ConsentManagement"],
|
|
166
|
+
|
|
167
|
+
// Request reference (optional)
|
|
168
|
+
// Will be attached to data subject requests
|
|
169
|
+
requestReference: "<reference>", // e.g. some uuid or id to match our created records with your frontend flows
|
|
170
|
+
|
|
171
|
+
// Limit consent view to specific data subjects (optional)
|
|
172
|
+
dataSubjects: ["customer", "employee"],
|
|
173
|
+
|
|
174
|
+
// File upload configuration (optional)
|
|
175
|
+
fileRequisites: {
|
|
176
|
+
allowedExtensions: ["pdf", "png", "jpeg", "jpg"],
|
|
177
|
+
maxFileSize: 5 * 1024 * 1024, // 5MB
|
|
178
|
+
},
|
|
179
|
+
|
|
180
|
+
// Common options
|
|
181
|
+
onEvent: (event) => console.log(event),
|
|
182
|
+
onReady: () => console.log("PrivacyCenterBox is ready"), // Optional
|
|
183
|
+
isSandbox: true, // Optional
|
|
184
|
+
appearance: {}, // Optional
|
|
185
|
+
};
|
|
186
|
+
|
|
187
|
+
// Wait for DOM to be fully loaded
|
|
188
|
+
document.addEventListener("DOMContentLoaded", () => {
|
|
189
|
+
const privacyCenter = new PrivacyCenterBox(privacyCenterOptions);
|
|
190
|
+
privacyCenter.mount("#privacy-center-box");
|
|
191
|
+
});
|
|
192
|
+
</script>
|
|
193
|
+
```
|
|
32
194
|
|
|
33
|
-
|
|
195
|
+
### Attribute Descriptions
|
|
196
|
+
|
|
197
|
+
- `sessionToken`: Use this to authenticate a session directly.
|
|
198
|
+
- `companyId`: The company identifier. Must start with `com_`. Use this when Privacy Center is mounted in a non authenticated environment.
|
|
199
|
+
- `enabledFeatures`: Optional array of features to show. Supported values: `"DataSubjectRequest"`, `"ConsentManagement"`.
|
|
200
|
+
- `requestReference`: Optional string, intended to be a reference of the current session. It will be attached to created data subject requests.
|
|
201
|
+
- `dataSubjects`: Optional array of data subject categories. When present, the consent management view only shows consent for the specified categories. Supported values include: `"anonymous_user"`, `"citizen_voter"`, `"commuter"`, `"consultant"`, `"customer"`, `"employee"`, `"job_applicant"`, `"next_of_kin"`, `"passenger"`, `"patient"`, `"prospect"`, `"shareholder"`, `"supplier_vendor"`, `"trainee"`, `"visitor"`.
|
|
202
|
+
- `fileRequisites`: Optional object to configure file upload constraints.
|
|
203
|
+
- `allowedExtensions`: Array of allowed file extensions (e.g. `['pdf', 'jpg']`). Default: `['pdf', 'png', 'jpeg', 'jpg']`.
|
|
204
|
+
- `maxFileSize`: Maximum file size in bytes. Default: `5 * 1024 * 1024` (5MB).
|
|
205
|
+
- `isSandbox`: Whether to use the sandbox environment. Defaults to `false`.
|
|
206
|
+
- `appearance`: Customize the iframe appearance. See Appearance section below.
|
|
207
|
+
- `onEvent`: Callback that receives events from the iframe.
|
|
208
|
+
- `onReady`: Optional callback fired when the iframe becomes ready.
|
|
209
|
+
|
|
210
|
+
Note:
|
|
211
|
+
- When `sessionToken` is provided, do not pass `companyId`.
|
|
212
|
+
|
|
213
|
+
### Privacy Center Events
|
|
214
|
+
|
|
215
|
+
- **`REQUEST_SUBMITTED`**: This event occurs when a user successfully submits a Data Subject Request. The event object includes:
|
|
216
|
+
- `eventName`: The name of the event, in this case, `'REQUEST_SUBMITTED'`.
|
|
217
|
+
- `kind`: The kind of the Data Subject Request submitted. Supported values are: `access`, `opposition`, `rectification`, `suppression` and `portability`
|
|
34
218
|
|
|
35
219
|
## Disclosure Request
|
|
36
220
|
|
|
221
|
+
> 📖 [Integration Guide](https://docs.soyio.id/docs/integration-guide/disclosure/introduction)
|
|
222
|
+
|
|
223
|
+
> [!NOTE]
|
|
224
|
+
> In Safari browsers, disclosure requests can only be opened as a result of a direct user interaction (like a click event). This is due to Safari's security policies regarding popup windows. Always ensure the disclosure request initialization is triggered by a user action when supporting Safari browsers.
|
|
225
|
+
|
|
37
226
|
A **`disclosure_request`** is a process that a user goes through where they are verified, and then they share the necessary data as required by each company.
|
|
38
227
|
This verification can happen in one of the following two ways:
|
|
39
228
|
|
|
@@ -162,6 +351,8 @@ The `onEvent` callback is designed to handle various events that occur during wi
|
|
|
162
351
|
|
|
163
352
|
## Signature Attempt
|
|
164
353
|
|
|
354
|
+
> 📖 [Integration Guide](https://docs.soyio.id/docs/integration-guide/signature/introduction)
|
|
355
|
+
|
|
165
356
|
The **`signature_attempt`** is a process where, using a previously created `signature_attempt_id`, a request is initiated in which a user can digitally sign a document. To sign the document, the user must be authenticated. This authentication can occur either through an access key or facial video. It's important to note that for this request, the user must have been previously verified with Soyio.
|
|
166
357
|
|
|
167
358
|
```html
|
|
@@ -211,6 +402,7 @@ Optional props:
|
|
|
211
402
|
|
|
212
403
|
### Signature Attempt Attribute Descriptions
|
|
213
404
|
|
|
405
|
+
|
|
214
406
|
- **`signatureAttemptId`**: Identifier of signature attempt obtained when creating the `SignatureAttempt`. It must start with `'sa_'`.
|
|
215
407
|
- **`isSandbox`**: Indicates if the widget should operate in sandbox mode, defaulting to `false`.
|
|
216
408
|
- **`onEvent`**: A callback function triggered upon event occurrences, used for capturing and logging event-related data.
|
|
@@ -218,6 +410,8 @@ Optional props:
|
|
|
218
410
|
|
|
219
411
|
## Auth Request
|
|
220
412
|
|
|
413
|
+
> 📖 [Integration Guide](https://docs.soyio.id/docs/integration-guide/authentication/introduction)
|
|
414
|
+
|
|
221
415
|
The **`auth_request`** is a process where, using a previously created `auth_request_id`, a request is initiated in which a user can authenticate. This authentication can occur either through an access key or facial video. It's important to note that for this request, the user must have been previously verified with Soyio.
|
|
222
416
|
|
|
223
417
|
```html
|
|
@@ -260,157 +454,11 @@ Optional props:
|
|
|
260
454
|
- **`onEvent`**: A callback function triggered upon event occurrences, used for capturing and logging event-related data.
|
|
261
455
|
- **`customColor`**: A hex code string that specifies the base color of the interface.
|
|
262
456
|
|
|
263
|
-
##
|
|
264
|
-
|
|
265
|
-
The **`ConsentBox`** is a component that allows you to embed a consent request directly within your webpage, rather than opening it in a popup window. This is particularly useful when you want to integrate the consent flow seamlessly into your application's interface.
|
|
266
|
-
|
|
267
|
-
```html
|
|
268
|
-
<!-- Add a container div where the consent request will be mounted -->
|
|
269
|
-
<div id="consent-request-box"></div>
|
|
270
|
-
|
|
271
|
-
<script>
|
|
272
|
-
import { ConsentBox } from "@soyio/soyio-widget";
|
|
273
|
-
|
|
274
|
-
// Configuration for the consent request
|
|
275
|
-
const consentOptions = {
|
|
276
|
-
consentTemplateId: "<consent template id>",
|
|
277
|
-
onEvent: (data) => console.log(data),
|
|
278
|
-
isSandbox: true, // Optional
|
|
279
|
-
appearance: {}, // Optional
|
|
280
|
-
actionToken: "<action token>", // Optional
|
|
281
|
-
entityId: "<entity id>", // Optional
|
|
282
|
-
context: "<context>", // Optional
|
|
283
|
-
onReady: () => console.log("ConsentBox is ready"), // Optional
|
|
284
|
-
optionalReconsentBehavior: "notice", // Optional
|
|
285
|
-
mandatoryReconsentBehavior: "notice", // Optional
|
|
286
|
-
};
|
|
287
|
-
|
|
288
|
-
// Wait for DOM to be fully loaded
|
|
289
|
-
document.addEventListener("DOMContentLoaded", () => {
|
|
290
|
-
// Create and mount the consent request box
|
|
291
|
-
const consentBox = new ConsentBox(consentOptions);
|
|
292
|
-
consentBox.mount("#consent-request-box");
|
|
293
|
-
});
|
|
294
|
-
</script>
|
|
295
|
-
```
|
|
296
|
-
|
|
297
|
-
### Consent Request Box Events
|
|
298
|
-
|
|
299
|
-
The `onEvent` follows the following format:
|
|
300
|
-
|
|
301
|
-
```typescript
|
|
302
|
-
{
|
|
303
|
-
eventName: 'CONSENT_CHECKBOX_CHANGE',
|
|
304
|
-
isSelected: boolean
|
|
305
|
-
actionToken: string,
|
|
306
|
-
}
|
|
307
|
-
```
|
|
308
|
-
|
|
309
|
-
### Methods
|
|
310
|
-
|
|
311
|
-
- **`getState()`**: Returns the current state of the consent box. The returned object has the following structure:
|
|
312
|
-
|
|
313
|
-
```typescript
|
|
314
|
-
{
|
|
315
|
-
isSelected: boolean,
|
|
316
|
-
actionToken: string | null,
|
|
317
|
-
}
|
|
318
|
-
|
|
319
|
-
```
|
|
320
|
-
|
|
321
|
-
### Attribute Descriptions
|
|
322
|
-
|
|
323
|
-
- **`consentTemplateId`**: Identifier of consent template. It must start with `'constpl_'`.
|
|
324
|
-
- **`isSelected`**: Boolean value indicating whether the consent checkbox is selected or not.
|
|
325
|
-
- **`actionToken`**: token containing necessary information for creation of the consent commit. [Learn more](https://docs.soyio.id/docs/api/resources/create-consent-request).
|
|
326
|
-
- **`appearance`**: Customize the appearance of the iframe. [Learn more](https://docs.soyio.id/docs/integration-guide/modules/consent).
|
|
327
|
-
- **`actionToken`**: In case of losing the state of the consent (i.e. page reload), you can use a previously generated `actionToken` to restore the state of the consent.
|
|
328
|
-
- **`entityId`**: Identifier of the `entity` associated with a `ConsentAction`. If provided and a consent was previously granted by this entity, the UI will display a message indicating that consent has already been given.
|
|
329
|
-
- **`context`**: Additional information that will be saved with the consent. Useful when you want to track the consent from a specific context.
|
|
330
|
-
- **`onReady`**: Optional callback that executes when the consent box is ready to use. You can use this to handle logic when the iframe is not mounted yet.
|
|
331
|
-
- **`optionalReconsentBehavior`**: What should happen when the consent is initialized with an `entityId` that has already given consent on an optional category.
|
|
332
|
-
- `notice` will show a message letting the user know that they have already given consent,
|
|
333
|
-
- `askAgain` will show the consent as if it wasn't given in the first place,
|
|
334
|
-
- `hide` will not show the consent at all.
|
|
335
|
-
|
|
336
|
-
We strongly recommend using `notice` so the user doesn't have to give the consent again and knows what they have already given consent to.
|
|
337
|
-
- **`mandatoryReconsentBehavior`**: What should happen when the consent is initialized with an `entityId` that has already given consent on a mandatory category.
|
|
338
|
-
- `notice` will show a message letting the user know that they have already given consent,
|
|
339
|
-
- `askAgain` will show the consent as if it wasn't given in the first place,
|
|
340
|
-
|
|
341
|
-
We don't support hiding the mandatory consent, and we strongly recommend using `notice` so the user doesn't have to give the consent again and knows what they have already given consent to.
|
|
342
|
-
|
|
343
|
-
## Privacy Center
|
|
344
|
-
|
|
345
|
-
The `PrivacyCenterBox` lets you embed the Privacy Center inside your page. You can scope which features to show and which data subjects are relevant to your interface. For more info check [our docs](https://docs.soyio.id/).
|
|
346
|
-
|
|
347
|
-
```html
|
|
348
|
-
<!-- Add a container div where the Privacy Center will be mounted -->
|
|
349
|
-
<div id="privacy-center-box"></div>
|
|
350
|
-
|
|
351
|
-
<script>
|
|
352
|
-
import { PrivacyCenterBox } from "@soyio/soyio-widget";
|
|
353
|
-
|
|
354
|
-
// Configuration for the Privacy Center
|
|
355
|
-
const privacyCenterOptions = {
|
|
356
|
-
// Choose ONE of the following authentication modes:
|
|
357
|
-
// 1) Public mode
|
|
358
|
-
companyId: "<company id>", // e.g. com_...
|
|
359
|
-
|
|
360
|
-
// 2) Authenticated mode
|
|
361
|
-
// sessionToken: "<session token>",
|
|
362
|
-
|
|
363
|
-
// Feature flags (optional)
|
|
364
|
-
enabledFeatures: ["DataSubjectRequest", "ConsentManagement"],
|
|
365
|
-
|
|
366
|
-
// Request reference (optional)
|
|
367
|
-
// Will be attached to data subject requests
|
|
368
|
-
requestReference: "<reference>", // e.g. some uuid or id to match our created records with your frontend flows
|
|
369
|
-
|
|
370
|
-
// Limit consent view to specific data subjects (optional)
|
|
371
|
-
dataSubjects: ["customer", "employee"],
|
|
372
|
-
|
|
373
|
-
// Common options
|
|
374
|
-
onEvent: (event) => console.log(event),
|
|
375
|
-
onReady: () => console.log("PrivacyCenterBox is ready"), // Optional
|
|
376
|
-
isSandbox: true, // Optional
|
|
377
|
-
appearance: {}, // Optional
|
|
378
|
-
};
|
|
379
|
-
|
|
380
|
-
// Wait for DOM to be fully loaded
|
|
381
|
-
document.addEventListener("DOMContentLoaded", () => {
|
|
382
|
-
const privacyCenter = new PrivacyCenterBox(privacyCenterOptions);
|
|
383
|
-
privacyCenter.mount("#privacy-center-box");
|
|
384
|
-
});
|
|
385
|
-
</script>
|
|
386
|
-
```
|
|
387
|
-
|
|
388
|
-
### Attribute Descriptions
|
|
389
|
-
|
|
390
|
-
- `sessionToken`: Use this to authenticate a session directly.
|
|
391
|
-
- `companyId`: The company identifier. Must start with `com_`. Use this when Privacy Center is mounted in a non authenticated environment.
|
|
392
|
-
- `enabledFeatures`: Optional array of features to show. Supported values: `"DataSubjectRequest"`, `"ConsentManagement"`.
|
|
393
|
-
- `requestReference`: Optional string, intended to be a reference of the current session. It will be attached to created data subject requests.
|
|
394
|
-
- `dataSubjects`: Optional array of data subject categories. When present, the consent management view only shows consent for the specified categories. Supported values include: `"anonymous_user"`, `"citizen_voter"`, `"commuter"`, `"consultant"`, `"customer"`, `"employee"`, `"job_applicant"`, `"next_of_kin"`, `"passenger"`, `"patient"`, `"prospect"`, `"shareholder"`, `"supplier_vendor"`, `"trainee"`, `"visitor"`.
|
|
395
|
-
- `isSandbox`: Whether to use the sandbox environment. Defaults to `false`.
|
|
396
|
-
- `appearance`: Customize the iframe appearance. See Appearance section below.
|
|
397
|
-
- `onEvent`: Callback that receives events from the iframe.
|
|
398
|
-
- `onReady`: Optional callback fired when the iframe becomes ready.
|
|
399
|
-
|
|
400
|
-
Note:
|
|
401
|
-
- When `sessionToken` is provided, do not pass `companyId`.
|
|
402
|
-
|
|
403
|
-
### Privacy Center Events
|
|
404
|
-
|
|
405
|
-
- **`REQUEST_SUBMITTED`**: This event occurs when a user successfully submits a Data Subject Request. The event object includes:
|
|
406
|
-
- `eventName`: The name of the event, in this case, `'REQUEST_SUBMITTED'`.
|
|
407
|
-
- `kind`: The kind of the Data Subject Request submitted. Supported values are: `access`, `opposition`, `rectification`, `suppression` and `portability`
|
|
408
|
-
|
|
409
|
-
# Appearance
|
|
457
|
+
## Appearance
|
|
410
458
|
|
|
411
459
|
Customize the look and feel of Soyio UI components by passing an `appearance` object to the configuration. The appearance object supports themes, CSS variables, and CSS rules for granular control over the styling.
|
|
412
460
|
|
|
413
|
-
|
|
461
|
+
### Structure
|
|
414
462
|
|
|
415
463
|
The appearance object consists of three main sections:
|
|
416
464
|
|
|
@@ -422,61 +470,163 @@ const appearance = {
|
|
|
422
470
|
};
|
|
423
471
|
```
|
|
424
472
|
|
|
425
|
-
|
|
473
|
+
### Themes
|
|
426
474
|
|
|
427
475
|
Currently supported themes:
|
|
428
476
|
|
|
429
477
|
- `"soyio"` (default) - The standard Soyio theme
|
|
430
478
|
|
|
431
|
-
|
|
479
|
+
### Variables
|
|
432
480
|
|
|
433
481
|
Use variables to adjust common visual attributes across all components.
|
|
434
482
|
|
|
435
483
|
```javascript
|
|
436
484
|
interface Variables {
|
|
437
485
|
fontFamily?: string;
|
|
486
|
+
fontSizeBase?: string;
|
|
438
487
|
colorPrimary?: string;
|
|
488
|
+
colorSecondary?: string;
|
|
439
489
|
colorBackground?: string;
|
|
440
490
|
colorText?: string;
|
|
491
|
+
colorTextSecondary?: string;
|
|
492
|
+
colorTextSubtle?: string;
|
|
493
|
+
colorTextInverted?: string;
|
|
494
|
+
colorPrimarySurface?: string;
|
|
495
|
+
colorSurface?: string;
|
|
496
|
+
colorSurfaceMuted?: string;
|
|
497
|
+
colorSurfaceStrong?: string;
|
|
498
|
+
colorBorder?: string;
|
|
499
|
+
colorBorderMuted?: string;
|
|
500
|
+
colorSwitchBorder?: string;
|
|
501
|
+
colorInfo?: string;
|
|
502
|
+
colorInfoBg?: string;
|
|
503
|
+
colorSuccess?: string;
|
|
504
|
+
colorSuccessBg?: string;
|
|
505
|
+
colorWarning?: string;
|
|
506
|
+
colorWarningBg?: string;
|
|
507
|
+
colorDanger?: string;
|
|
508
|
+
colorDangerBg?: string;
|
|
509
|
+
colorOverlay?: string;
|
|
441
510
|
borderRadius?: string;
|
|
442
511
|
borderWidth?: string;
|
|
443
512
|
borderStyle?: string;
|
|
444
513
|
}
|
|
445
514
|
```
|
|
446
515
|
|
|
447
|
-
|
|
516
|
+
#### Available Variables
|
|
448
517
|
|
|
449
518
|
| Variable | Description | Default |
|
|
450
519
|
| ----------------- | ---------------------------------------- | ------------------------- |
|
|
451
|
-
| `fontFamily`
|
|
452
|
-
| `colorPrimary`
|
|
453
|
-
| `
|
|
454
|
-
| `
|
|
455
|
-
| `
|
|
456
|
-
| `
|
|
457
|
-
| `
|
|
458
|
-
| `
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
520
|
+
| `fontFamily` | The font stack to use for text | `"system-ui, sans-serif"` |
|
|
521
|
+
| `colorPrimary` | Primary color for interactive elements | `"#0570DE"` |
|
|
522
|
+
| `colorPrimarySurface` | Background color for primary elements (e.g. active tab) | `"#EEF2FF"` |
|
|
523
|
+
| `colorSecondary` | Secondary color for interactive elements | `"#A180F0"` |
|
|
524
|
+
| `colorBackground` | Background color | `"#FFFFFF"` |
|
|
525
|
+
| `colorSurface` | Surface color for cards and sections | `"#F9FAFB"` |
|
|
526
|
+
| `colorSurfaceMuted` | Muted surface color | `"#F3F4F6"` |
|
|
527
|
+
| `colorSurfaceStrong` | Strong surface color | `"#E5E7EB"` |
|
|
528
|
+
| `colorBorder` | Border color | `"#D1D5DB"` |
|
|
529
|
+
| `colorBorderMuted` | Muted border color | `"#E5E7EB"` |
|
|
530
|
+
| `colorSwitchBorder` | Border color for Switch component (unchecked) | `"#000000"` |
|
|
531
|
+
| `colorText` | Main text color | `"#1E1B4B"` |
|
|
532
|
+
| `colorTextSecondary` | Secondary text color | `"#6B7280"` |
|
|
533
|
+
| `colorTextSubtle` | Subtle text color | `"#9CA3AF"` |
|
|
534
|
+
| `colorTextInverted` | Inverted text color | `"#FFFFFF"` |
|
|
535
|
+
| `colorInfo` | Info status color | `"#1E40AF"` |
|
|
536
|
+
| `colorInfoBg` | Info status background color | `"#E0E7FF"` |
|
|
537
|
+
| `colorSuccess` | Success status color | `"#15803D"` |
|
|
538
|
+
| `colorSuccessBg` | Success status background color | `"#DCFCE7"` |
|
|
539
|
+
| `colorWarning` | Warning status color | `"#B45309"` |
|
|
540
|
+
| `colorWarningBg` | Warning status background color | `"#FEF3C7"` |
|
|
541
|
+
| `colorDanger` | Danger status color | `"#EF4444"` |
|
|
542
|
+
| `colorDangerBg` | Danger status background color | `"#FEF2F2"` |
|
|
543
|
+
| `colorOverlay` | Overlay color | `"rgba(0, 0, 0, 0.5)"` |
|
|
544
|
+
| `borderRadius` | Base border radius (scales proportionally for different sizes) | `"0.25rem"` |
|
|
545
|
+
| `borderWidth` | Border width for elements | `"1px"` |
|
|
546
|
+
| `borderStyle` | Border style for elements | `"solid"` |
|
|
547
|
+
|
|
548
|
+
> **Note on Border Radius:** The `borderRadius` variable serves as a base unit. Larger components (like Inputs and Buttons) use a multiple of this value (typically 2x), while smaller elements use a fraction or the base value itself. This ensures consistent scaling across all UI elements.
|
|
549
|
+
|
|
550
|
+
### Rules
|
|
551
|
+
|
|
552
|
+
The `rules` object allows you to apply custom CSS to specific elements. Soyio supports styling for various components including inputs, buttons, switches, and more.
|
|
553
|
+
|
|
554
|
+
#### Supported rules
|
|
555
|
+
|
|
556
|
+
The rules are grouped by component category:
|
|
557
|
+
|
|
558
|
+
##### Layout
|
|
559
|
+
- `.MainContainer` - The main container.
|
|
560
|
+
- `.Card` - Card containers.
|
|
561
|
+
- `.Dialog` - Dialog containers.
|
|
562
|
+
- `.DialogOverlay` - Dialog overlays.
|
|
563
|
+
- `.DialogContent` - Dialog content areas.
|
|
564
|
+
|
|
565
|
+
##### Typography
|
|
566
|
+
- `.Title` - Title text.
|
|
567
|
+
- `.Description` - Description text.
|
|
568
|
+
|
|
569
|
+
##### Inputs
|
|
570
|
+
- `.Input` - Input fields.
|
|
571
|
+
- `.Label` - Labels.
|
|
572
|
+
- `.TextArea` - Text area inputs.
|
|
573
|
+
- `.Select` - Select dropdowns.
|
|
574
|
+
- `.Combobox` - Combobox inputs.
|
|
575
|
+
- `.NinInput` - Styles the input field for national identity numbers.
|
|
576
|
+
|
|
577
|
+
##### Buttons & Links
|
|
467
578
|
- `.Button` - The button component.
|
|
468
|
-
- `.
|
|
469
|
-
- `.CheckboxInput` - The checkbox input element.
|
|
470
|
-
- `.CheckboxLabel` - The checkbox label.
|
|
579
|
+
- `.Link` - Links.
|
|
471
580
|
|
|
472
|
-
|
|
581
|
+
##### Selection Controls
|
|
473
582
|
|
|
474
|
-
|
|
583
|
+
**Checkbox**
|
|
584
|
+
|
|
475
585
|
|
|
586
|
+
- `.Checkbox` - The checkbox container.
|
|
587
|
+
- `.CheckboxInput` - The styled checkbox element (supports `borderRadius`, `borderColor`, `backgroundColor`).
|
|
588
|
+
- `.CheckboxLabel` - The checkbox label.
|
|
589
|
+
- `.CheckboxCheck` - The checkmark icon inside the checkbox.
|
|
476
590
|
- `.CheckboxInput--checked` - The checked state of the checkbox
|
|
591
|
+
- `.CheckboxInput--focus` - Focus state of the checkbox (visible focus ring)
|
|
477
592
|
- `.CheckboxInput:hover` - Hover state of the checkbox
|
|
478
|
-
|
|
479
|
-
|
|
593
|
+
|
|
594
|
+
|
|
595
|
+
**Radio**
|
|
596
|
+
- `.Radio` - Radio button containers.
|
|
597
|
+
- `.RadioLabel` - Radio button labels.
|
|
598
|
+
|
|
599
|
+
**Switch**
|
|
600
|
+
- `.Switch` - Switch toggles (wrapper).
|
|
601
|
+
- `.SwitchRoot` - Switch control (track).
|
|
602
|
+
- `.SwitchThumb` - Switch thumb (circle).
|
|
603
|
+
- `.SwitchIcon` - Switch icons (check/cross).
|
|
604
|
+
- `.SwitchRoot--checked` - Checked state of the switch track
|
|
605
|
+
- `.SwitchThumb--checked` - Checked state of the switch thumb
|
|
606
|
+
|
|
607
|
+
**Radio Card**
|
|
608
|
+
- `.RadioCard` - Styles the wrapper card element of a radio card item.
|
|
609
|
+
- `.RadioCardIndicator` - Styles the container of the radio indicator (circle) inside a radio card.
|
|
610
|
+
- `.RadioCardIndicatorPoint` - Styles the inner point of the radio indicator inside a radio card.
|
|
611
|
+
|
|
612
|
+
##### Feedback
|
|
613
|
+
- `.Loader` - Loading indicators.
|
|
614
|
+
- `.ErrorMessage` - Error message text.
|
|
615
|
+
- `.TooltipContent` - Styles the content popover of a tooltip.
|
|
616
|
+
|
|
617
|
+
**Alert**
|
|
618
|
+
- `.Alert` - Alert boxes.
|
|
619
|
+
- `.Alert--error` - Error alert variant.
|
|
620
|
+
- `.Alert--warning` - Warning alert variant.
|
|
621
|
+
- `.Alert--information` - Information alert variant.
|
|
622
|
+
- `.Alert--success` - Success alert variant.
|
|
623
|
+
|
|
624
|
+
**Chip**
|
|
625
|
+
- `.Chip` - Chips/Tags.
|
|
626
|
+
- `.Chip--info` - Info chip variant.
|
|
627
|
+
- `.Chip--green` - Green chip variant.
|
|
628
|
+
- `.Chip--red` - Red chip variant.
|
|
629
|
+
- `.Chip--amber` - Amber chip variant.
|
|
480
630
|
|
|
481
631
|
### Example Configuration
|
|
482
632
|
|
|
@@ -526,6 +676,22 @@ const appearance = {
|
|
|
526
676
|
outline: "none",
|
|
527
677
|
boxShadow: "0 0 0 2px var(--colorPrimary)",
|
|
528
678
|
},
|
|
679
|
+
".SwitchRoot": {
|
|
680
|
+
backgroundColor: "#e5e7eb",
|
|
681
|
+
borderRadius: "9999px",
|
|
682
|
+
boxShadow: "none", // Remove default shadow
|
|
683
|
+
},
|
|
684
|
+
".SwitchRoot--checked": {
|
|
685
|
+
backgroundColor: "var(--colorPrimary)",
|
|
686
|
+
},
|
|
687
|
+
".SwitchThumb": {
|
|
688
|
+
backgroundColor: "white",
|
|
689
|
+
borderRadius: "9999px",
|
|
690
|
+
boxShadow: "0 2px 4px rgba(0,0,0,0.2)",
|
|
691
|
+
},
|
|
692
|
+
".SwitchIcon": {
|
|
693
|
+
display: "none", // Hide the check/cross icons
|
|
694
|
+
},
|
|
529
695
|
},
|
|
530
696
|
};
|
|
531
697
|
```
|
|
@@ -640,7 +806,7 @@ export default function PrivacyCenterContainer() {
|
|
|
640
806
|
|
|
641
807
|
return (
|
|
642
808
|
<div>
|
|
643
|
-
{isClient &&
|
|
809
|
+
{isClient &&
|
|
644
810
|
<React.Suspense fallback={
|
|
645
811
|
<div>
|
|
646
812
|
Loading...
|
|
@@ -653,3 +819,20 @@ export default function PrivacyCenterContainer() {
|
|
|
653
819
|
)
|
|
654
820
|
}
|
|
655
821
|
```
|
|
822
|
+
|
|
823
|
+
## Development
|
|
824
|
+
|
|
825
|
+
To run the widget customization smoke test locally:
|
|
826
|
+
|
|
827
|
+
```sh
|
|
828
|
+
yarn run smoke
|
|
829
|
+
```
|
|
830
|
+
|
|
831
|
+
The smoke test configuration is loaded from `smoke-test/.env.development`. You can modify this file to change the default values:
|
|
832
|
+
|
|
833
|
+
```bash
|
|
834
|
+
VITE_COMPANY_ID=com_test
|
|
835
|
+
VITE_PRIVACY_CENTER_URL=http://localhost:5173
|
|
836
|
+
VITE_CONSENT_URL=http://localhost:5173
|
|
837
|
+
VITE_CONSENT_TEMPLATE_ID=constpl_test
|
|
838
|
+
```
|