tia-gpc-widget 1.1.0 → 1.1.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 +1388 -1388
- package/dist/loader.js +271 -271
- package/dist/loader.min.js +1 -1
- package/dist/tia-gpc-widget.standalone.js.map +1 -1
- package/dist/tia-gpc.cjs.js.map +1 -1
- package/dist/tia-gpc.es.js.map +1 -1
- package/dist/version.json +15 -15
- package/package.json +89 -89
package/README.md
CHANGED
|
@@ -1,1388 +1,1388 @@
|
|
|
1
|
-
# TIA GPC Widget
|
|
2
|
-
|
|
3
|
-
Intelligent chat widget for TIA GPC integration. Compatible with **React, HTML, Angular, ASP.NET, Vue, and any other framework**.
|
|
4
|
-
|
|
5
|
-
[](https://www.npmjs.com/package/tia-gpc-widget)
|
|
6
|
-
[](https://www.jsdelivr.com/package/npm/tia-gpc-widget)
|
|
7
|
-
[](LICENSE)
|
|
8
|
-
|
|
9
|
-
---
|
|
10
|
-
|
|
11
|
-
## 📋 Table of Contents
|
|
12
|
-
|
|
13
|
-
- [Features](#-features)
|
|
14
|
-
- [Installation](#-installation)
|
|
15
|
-
- [Option 1: NPM (For React/Node Projects)](#option-1-npm-for-reactnode-projects)
|
|
16
|
-
- [Option 2: CDN (For HTML, Angular, ASP.NET, etc.)](#option-2-cdn-for-html-angular-aspnet-etc)
|
|
17
|
-
- [Quick Start](#-quick-start)
|
|
18
|
-
- [Framework Examples](#-framework-examples)
|
|
19
|
-
- [React](#1-react)
|
|
20
|
-
- [HTML / Vanilla JavaScript](#2-html--vanilla-javascript)
|
|
21
|
-
- [Angular](#3-angular)
|
|
22
|
-
- [ASP.NET / ASPX](#4-aspnet--aspx)
|
|
23
|
-
- [Vue.js](#5-vuejs)
|
|
24
|
-
- [Next.js](#6-nextjs)
|
|
25
|
-
- [PHP](#7-php)
|
|
26
|
-
- [API & Configuration](#-api--configuration)
|
|
27
|
-
- [Props/Attributes](#propsattributes)
|
|
28
|
-
- [Events](#events)
|
|
29
|
-
- [Programmatic API (JavaScript)](#programmatic-api-javascript)
|
|
30
|
-
- [Customization](#-customization)
|
|
31
|
-
- [Themes](#themes)
|
|
32
|
-
- [Positions](#positions)
|
|
33
|
-
- [Languages](#languages)
|
|
34
|
-
- [Colors](#colors)
|
|
35
|
-
- [Build & Development](#-build--development)
|
|
36
|
-
- [Publishing](#-publishing)
|
|
37
|
-
- [Support](#-support)
|
|
38
|
-
|
|
39
|
-
---
|
|
40
|
-
|
|
41
|
-
## 🚀 Features
|
|
42
|
-
|
|
43
|
-
- ✅ **Framework Agnostic**: Works in React, Angular, Vue, ASP.NET, plain HTML, etc.
|
|
44
|
-
- ✅ **Web Component**: Based on native web standards
|
|
45
|
-
- ✅ **Themes**: Light, dark, or automatic mode
|
|
46
|
-
- ✅ **Internationalization**: Spanish, English, French
|
|
47
|
-
- ✅ **Responsive**: Adaptive design for mobile and desktop
|
|
48
|
-
- ✅ **Customizable**: Colors, positions, dimensions
|
|
49
|
-
- ✅ **TypeScript Ready**: Types included
|
|
50
|
-
- ✅ **Zero Dependencies**: Standalone bundle includes everything needed
|
|
51
|
-
|
|
52
|
-
---
|
|
53
|
-
|
|
54
|
-
## 🚀 Auto-Update Loader (Recommended)
|
|
55
|
-
|
|
56
|
-
**NEW!** Install once, get updates forever. No more manual version updates!
|
|
57
|
-
|
|
58
|
-
The **TIA GPC Widget Loader** is a small, stable script (~1KB gzipped) that automatically loads the latest version of the widget. Your clients install it **ONCE** and receive all future updates automatically.
|
|
59
|
-
|
|
60
|
-
### Quick Start with Loader
|
|
61
|
-
|
|
62
|
-
```html
|
|
63
|
-
<!DOCTYPE html>
|
|
64
|
-
<html lang="en">
|
|
65
|
-
<head>
|
|
66
|
-
<meta charset="UTF-8">
|
|
67
|
-
<title>My App with TIA GPC</title>
|
|
68
|
-
</head>
|
|
69
|
-
<body>
|
|
70
|
-
<h1>My Application</h1>
|
|
71
|
-
|
|
72
|
-
<!-- TIA GPC Widget Loader (install once, updates forever) -->
|
|
73
|
-
<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@latest/dist/loader.min.js"></script>
|
|
74
|
-
|
|
75
|
-
<!-- Widget element -->
|
|
76
|
-
<tia-gpc-widget
|
|
77
|
-
token="your-license-token-here"
|
|
78
|
-
theme="auto"
|
|
79
|
-
position="bottom-right"
|
|
80
|
-
language="en"
|
|
81
|
-
></tia-gpc-widget>
|
|
82
|
-
</body>
|
|
83
|
-
</html>
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
**Benefits:**
|
|
87
|
-
- ✅ Install once, never update manually again
|
|
88
|
-
- ✅ Automatic updates when you publish new versions
|
|
89
|
-
- ✅ Built-in error handling and retries
|
|
90
|
-
- ✅ Support for stable/beta channels
|
|
91
|
-
- ✅ Extremely small (~1KB gzipped)
|
|
92
|
-
- ✅ Works with all frameworks (HTML, React, Angular, ASP.NET, etc.)
|
|
93
|
-
|
|
94
|
-
[See complete loader documentation and examples →](#loader-advanced-usage)
|
|
95
|
-
|
|
96
|
-
---
|
|
97
|
-
|
|
98
|
-
## 📦 Installation
|
|
99
|
-
|
|
100
|
-
### Option 1: Auto-Update Loader (Recommended)
|
|
101
|
-
|
|
102
|
-
Use the loader for automatic updates:
|
|
103
|
-
|
|
104
|
-
```html
|
|
105
|
-
<!-- jsDelivr (Recommended) -->
|
|
106
|
-
<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@latest/dist/loader.min.js"></script>
|
|
107
|
-
|
|
108
|
-
<!-- unpkg -->
|
|
109
|
-
<script src="https://unpkg.com/tia-gpc-widget@latest/dist/loader.min.js"></script>
|
|
110
|
-
```
|
|
111
|
-
|
|
112
|
-
Then use the widget as normal:
|
|
113
|
-
```html
|
|
114
|
-
<tia-gpc-widget token="your-token" theme="auto"></tia-gpc-widget>
|
|
115
|
-
```
|
|
116
|
-
|
|
117
|
-
### Option 2: NPM (For React/Node Projects)
|
|
118
|
-
|
|
119
|
-
```bash
|
|
120
|
-
npm install tia-gpc-widget
|
|
121
|
-
```
|
|
122
|
-
|
|
123
|
-
or with yarn:
|
|
124
|
-
|
|
125
|
-
```bash
|
|
126
|
-
yarn add tia-gpc-widget
|
|
127
|
-
```
|
|
128
|
-
|
|
129
|
-
or with pnpm:
|
|
130
|
-
|
|
131
|
-
```bash
|
|
132
|
-
pnpm add tia-gpc-widget
|
|
133
|
-
```
|
|
134
|
-
|
|
135
|
-
### Option 3: Direct CDN (Legacy - Not Recommended)
|
|
136
|
-
|
|
137
|
-
⚠️ **Note:** This method is still supported but **not recommended** for new installations.
|
|
138
|
-
It requires manual updates every time we release a new version.
|
|
139
|
-
**Use the Auto-Update Loader instead** (see Option 1 above).
|
|
140
|
-
|
|
141
|
-
#### jsDelivr - Fixed Version
|
|
142
|
-
|
|
143
|
-
```html
|
|
144
|
-
<!-- ⚠️ Legacy method: Requires manual version updates -->
|
|
145
|
-
<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.9/dist/tia-gpc-widget.standalone.js"></script>
|
|
146
|
-
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.9/dist/tia-gpc-widget.standalone.css">
|
|
147
|
-
```
|
|
148
|
-
|
|
149
|
-
#### unpkg - Fixed Version
|
|
150
|
-
|
|
151
|
-
```html
|
|
152
|
-
<!-- ⚠️ Legacy method: Requires manual version updates -->
|
|
153
|
-
<script src="https://unpkg.com/tia-gpc-widget@1.0.9/dist/tia-gpc-widget.standalone.js"></script>
|
|
154
|
-
<link rel="stylesheet" href="https://unpkg.com/tia-gpc-widget@1.0.9/dist/tia-gpc-widget.standalone.css">
|
|
155
|
-
```
|
|
156
|
-
|
|
157
|
-
**Why use the loader instead?**
|
|
158
|
-
- ✅ Automatic updates - no code changes needed
|
|
159
|
-
- ✅ Always get bug fixes and improvements
|
|
160
|
-
- ✅ Smaller initial load (~2KB vs ~420KB until needed)
|
|
161
|
-
- ✅ Built-in error handling and fallbacks
|
|
162
|
-
|
|
163
|
-
**For existing installations:** See [Migration Guide](MIGRATION.md) to upgrade to the auto-update loader.
|
|
164
|
-
|
|
165
|
-
---
|
|
166
|
-
|
|
167
|
-
## ⚡ Quick Start
|
|
168
|
-
|
|
169
|
-
### In Plain HTML
|
|
170
|
-
|
|
171
|
-
```html
|
|
172
|
-
<!DOCTYPE html>
|
|
173
|
-
<html lang="en">
|
|
174
|
-
<head>
|
|
175
|
-
<meta charset="UTF-8">
|
|
176
|
-
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
177
|
-
<title>My App with TIA GPC</title>
|
|
178
|
-
</head>
|
|
179
|
-
<body>
|
|
180
|
-
<h1>My Application</h1>
|
|
181
|
-
|
|
182
|
-
<!-- TIA GPC Widget -->
|
|
183
|
-
<tia-gpc-widget
|
|
184
|
-
token="your-license-token-here"
|
|
185
|
-
theme="auto"
|
|
186
|
-
position="bottom-right"
|
|
187
|
-
language="en"
|
|
188
|
-
></tia-gpc-widget>
|
|
189
|
-
|
|
190
|
-
<!-- Auto-Update Loader (loads latest version automatically) -->
|
|
191
|
-
<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@latest/dist/loader.min.js"></script>
|
|
192
|
-
</body>
|
|
193
|
-
</html>
|
|
194
|
-
```
|
|
195
|
-
|
|
196
|
-
### In React
|
|
197
|
-
|
|
198
|
-
```jsx
|
|
199
|
-
import { TiaGPCWidget } from 'tia-gpc-widget';
|
|
200
|
-
import 'tia-gpc-widget/styles';
|
|
201
|
-
|
|
202
|
-
function App() {
|
|
203
|
-
return (
|
|
204
|
-
<div>
|
|
205
|
-
<h1>My Application</h1>
|
|
206
|
-
<TiaGPCWidget
|
|
207
|
-
token="your-license-token-here"
|
|
208
|
-
theme="auto"
|
|
209
|
-
position="bottom-right"
|
|
210
|
-
language="en"
|
|
211
|
-
/>
|
|
212
|
-
</div>
|
|
213
|
-
);
|
|
214
|
-
}
|
|
215
|
-
|
|
216
|
-
export default App;
|
|
217
|
-
```
|
|
218
|
-
|
|
219
|
-
---
|
|
220
|
-
|
|
221
|
-
## 📚 Framework Examples
|
|
222
|
-
|
|
223
|
-
> **💡 Important:** The examples below may show both installation methods:
|
|
224
|
-
> - **Recommended:** Auto-Update Loader (install once, updates automatically)
|
|
225
|
-
> - **Legacy:** Direct CDN with fixed version (requires manual updates)
|
|
226
|
-
>
|
|
227
|
-
> **For new installations, always use the Auto-Update Loader** shown in [Option 1](#option-1-auto-update-loader-recommended).
|
|
228
|
-
|
|
229
|
-
### 1. React
|
|
230
|
-
|
|
231
|
-
#### Installation
|
|
232
|
-
|
|
233
|
-
```bash
|
|
234
|
-
npm install tia-gpc-widget
|
|
235
|
-
```
|
|
236
|
-
|
|
237
|
-
#### Basic Usage
|
|
238
|
-
|
|
239
|
-
```jsx
|
|
240
|
-
import { TiaGPCWidget } from 'tia-gpc-widget';
|
|
241
|
-
import 'tia-gpc-widget/styles';
|
|
242
|
-
|
|
243
|
-
function App() {
|
|
244
|
-
return (
|
|
245
|
-
<TiaGPCWidget
|
|
246
|
-
token="your-license-token"
|
|
247
|
-
theme="auto"
|
|
248
|
-
position="bottom-right"
|
|
249
|
-
language="en"
|
|
250
|
-
primaryColor="#2563eb"
|
|
251
|
-
onReady={() => console.log('Widget ready')}
|
|
252
|
-
onError={(error) => console.error('Error:', error)}
|
|
253
|
-
/>
|
|
254
|
-
);
|
|
255
|
-
}
|
|
256
|
-
```
|
|
257
|
-
|
|
258
|
-
#### Advanced Configuration
|
|
259
|
-
|
|
260
|
-
```jsx
|
|
261
|
-
import { TiaGPCWidget, WIDGET_POSITIONS, THEMES, LANGUAGES } from 'tia-gpc-widget';
|
|
262
|
-
import 'tia-gpc-widget/styles';
|
|
263
|
-
|
|
264
|
-
function App() {
|
|
265
|
-
const handleReady = () => {
|
|
266
|
-
console.log('✅ Widget initialized successfully');
|
|
267
|
-
};
|
|
268
|
-
|
|
269
|
-
const handleError = (error) => {
|
|
270
|
-
console.error('❌ Widget error:', error);
|
|
271
|
-
};
|
|
272
|
-
|
|
273
|
-
return (
|
|
274
|
-
<TiaGPCWidget
|
|
275
|
-
token="your-license-token"
|
|
276
|
-
theme={THEMES.AUTO}
|
|
277
|
-
position={WIDGET_POSITIONS.BOTTOM_RIGHT}
|
|
278
|
-
language={LANGUAGES.EN}
|
|
279
|
-
primaryColor="#10b981"
|
|
280
|
-
width="450px"
|
|
281
|
-
height="650px"
|
|
282
|
-
autoOpen={false}
|
|
283
|
-
showBranding={true}
|
|
284
|
-
mobileFullscreen={true}
|
|
285
|
-
onReady={handleReady}
|
|
286
|
-
onError={handleError}
|
|
287
|
-
onClose={() => console.log('Widget closed')}
|
|
288
|
-
/>
|
|
289
|
-
);
|
|
290
|
-
}
|
|
291
|
-
```
|
|
292
|
-
|
|
293
|
-
---
|
|
294
|
-
|
|
295
|
-
### 2. HTML / Vanilla JavaScript
|
|
296
|
-
|
|
297
|
-
#### Method 1: Using HTML element directly
|
|
298
|
-
|
|
299
|
-
```html
|
|
300
|
-
<!DOCTYPE html>
|
|
301
|
-
<html lang="en">
|
|
302
|
-
<head>
|
|
303
|
-
<meta charset="UTF-8">
|
|
304
|
-
<title>TIA GPC Widget - Plain HTML</title>
|
|
305
|
-
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.css">
|
|
306
|
-
</head>
|
|
307
|
-
<body>
|
|
308
|
-
<h1>My Website</h1>
|
|
309
|
-
|
|
310
|
-
<!-- Widget as HTML element -->
|
|
311
|
-
<tia-gpc-widget
|
|
312
|
-
token="your-license-token"
|
|
313
|
-
theme="light"
|
|
314
|
-
position="bottom-right"
|
|
315
|
-
language="en"
|
|
316
|
-
primary-color="#3b82f6"
|
|
317
|
-
width="400px"
|
|
318
|
-
height="600px"
|
|
319
|
-
auto-open="false"
|
|
320
|
-
show-branding="true"
|
|
321
|
-
></tia-gpc-widget>
|
|
322
|
-
|
|
323
|
-
<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.js"></script>
|
|
324
|
-
|
|
325
|
-
<!-- Optional events -->
|
|
326
|
-
<script>
|
|
327
|
-
const widget = document.querySelector('tia-gpc-widget');
|
|
328
|
-
|
|
329
|
-
widget.addEventListener('ready', () => {
|
|
330
|
-
console.log('Widget ready');
|
|
331
|
-
});
|
|
332
|
-
|
|
333
|
-
widget.addEventListener('error', (e) => {
|
|
334
|
-
console.error('Error:', e.detail);
|
|
335
|
-
});
|
|
336
|
-
|
|
337
|
-
widget.addEventListener('close', () => {
|
|
338
|
-
console.log('Widget closed');
|
|
339
|
-
});
|
|
340
|
-
</script>
|
|
341
|
-
</body>
|
|
342
|
-
</html>
|
|
343
|
-
```
|
|
344
|
-
|
|
345
|
-
#### Method 2: Programmatic creation with JavaScript
|
|
346
|
-
|
|
347
|
-
```html
|
|
348
|
-
<!DOCTYPE html>
|
|
349
|
-
<html lang="en">
|
|
350
|
-
<head>
|
|
351
|
-
<meta charset="UTF-8">
|
|
352
|
-
<title>TIA GPC Widget - Programmatic</title>
|
|
353
|
-
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.css">
|
|
354
|
-
</head>
|
|
355
|
-
<body>
|
|
356
|
-
<h1>My Website</h1>
|
|
357
|
-
<button id="create-widget">Create Widget</button>
|
|
358
|
-
|
|
359
|
-
<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.js"></script>
|
|
360
|
-
<script>
|
|
361
|
-
document.getElementById('create-widget').addEventListener('click', () => {
|
|
362
|
-
// Use the global TiaGPC API
|
|
363
|
-
const widget = TiaGPC.create({
|
|
364
|
-
token: 'your-license-token',
|
|
365
|
-
theme: 'auto',
|
|
366
|
-
position: TiaGPC.POSITIONS.BOTTOM_RIGHT,
|
|
367
|
-
language: TiaGPC.LANGUAGES.EN,
|
|
368
|
-
primaryColor: '#3b82f6',
|
|
369
|
-
autoOpen: false,
|
|
370
|
-
onReady: () => console.log('✅ Widget ready'),
|
|
371
|
-
onError: (error) => console.error('❌ Error:', error),
|
|
372
|
-
onClose: () => console.log('Widget closed')
|
|
373
|
-
});
|
|
374
|
-
|
|
375
|
-
console.log('Widget created:', widget);
|
|
376
|
-
});
|
|
377
|
-
|
|
378
|
-
// View widget information
|
|
379
|
-
TiaGPC.info();
|
|
380
|
-
</script>
|
|
381
|
-
</body>
|
|
382
|
-
</html>
|
|
383
|
-
```
|
|
384
|
-
|
|
385
|
-
---
|
|
386
|
-
|
|
387
|
-
### 3. Angular
|
|
388
|
-
|
|
389
|
-
#### Step 1: Install the widget
|
|
390
|
-
|
|
391
|
-
```bash
|
|
392
|
-
npm install tia-gpc-widget
|
|
393
|
-
```
|
|
394
|
-
|
|
395
|
-
#### Step 2: Configure Angular for Web Components
|
|
396
|
-
|
|
397
|
-
In `src/main.ts` or `src/polyfills.ts`, add:
|
|
398
|
-
|
|
399
|
-
```typescript
|
|
400
|
-
// Enable Custom Elements (Web Components)
|
|
401
|
-
import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
|
|
402
|
-
```
|
|
403
|
-
|
|
404
|
-
In your main module (`app.module.ts`):
|
|
405
|
-
|
|
406
|
-
```typescript
|
|
407
|
-
import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
|
|
408
|
-
import { BrowserModule } from '@angular/platform-browser';
|
|
409
|
-
import { AppComponent } from './app.component';
|
|
410
|
-
|
|
411
|
-
@NgModule({
|
|
412
|
-
declarations: [AppComponent],
|
|
413
|
-
imports: [BrowserModule],
|
|
414
|
-
schemas: [CUSTOM_ELEMENTS_SCHEMA], // ← Important
|
|
415
|
-
bootstrap: [AppComponent]
|
|
416
|
-
})
|
|
417
|
-
export class AppModule { }
|
|
418
|
-
```
|
|
419
|
-
|
|
420
|
-
#### Step 3: Import widget files
|
|
421
|
-
|
|
422
|
-
In `angular.json`, add the CSS and JS files:
|
|
423
|
-
|
|
424
|
-
```json
|
|
425
|
-
{
|
|
426
|
-
"projects": {
|
|
427
|
-
"your-project": {
|
|
428
|
-
"architect": {
|
|
429
|
-
"build": {
|
|
430
|
-
"options": {
|
|
431
|
-
"styles": [
|
|
432
|
-
"src/styles.css",
|
|
433
|
-
"node_modules/tia-gpc-widget/dist/tia-gpc-widget.standalone.css"
|
|
434
|
-
],
|
|
435
|
-
"scripts": [
|
|
436
|
-
"node_modules/tia-gpc-widget/dist/tia-gpc-widget.standalone.js"
|
|
437
|
-
]
|
|
438
|
-
}
|
|
439
|
-
}
|
|
440
|
-
}
|
|
441
|
-
}
|
|
442
|
-
}
|
|
443
|
-
}
|
|
444
|
-
```
|
|
445
|
-
|
|
446
|
-
#### Step 4: Use the widget in your component
|
|
447
|
-
|
|
448
|
-
```typescript
|
|
449
|
-
// app.component.ts
|
|
450
|
-
import { Component, OnInit } from '@angular/core';
|
|
451
|
-
|
|
452
|
-
declare global {
|
|
453
|
-
interface Window {
|
|
454
|
-
TiaGPC: any;
|
|
455
|
-
}
|
|
456
|
-
}
|
|
457
|
-
|
|
458
|
-
@Component({
|
|
459
|
-
selector: 'app-root',
|
|
460
|
-
template: `
|
|
461
|
-
<h1>My Angular Application</h1>
|
|
462
|
-
|
|
463
|
-
<!-- Option 1: Direct HTML element -->
|
|
464
|
-
<tia-gpc-widget
|
|
465
|
-
[attr.token]="widgetToken"
|
|
466
|
-
[attr.theme]="theme"
|
|
467
|
-
[attr.position]="position"
|
|
468
|
-
[attr.language]="language"
|
|
469
|
-
(ready)="onWidgetReady()"
|
|
470
|
-
(error)="onWidgetError($event)"
|
|
471
|
-
></tia-gpc-widget>
|
|
472
|
-
`
|
|
473
|
-
})
|
|
474
|
-
export class AppComponent implements OnInit {
|
|
475
|
-
widgetToken = 'your-license-token';
|
|
476
|
-
theme = 'auto';
|
|
477
|
-
position = 'bottom-right';
|
|
478
|
-
language = 'en';
|
|
479
|
-
|
|
480
|
-
ngOnInit() {
|
|
481
|
-
console.log('TiaGPC available:', window.TiaGPC);
|
|
482
|
-
}
|
|
483
|
-
|
|
484
|
-
onWidgetReady() {
|
|
485
|
-
console.log('✅ TIA GPC widget ready');
|
|
486
|
-
}
|
|
487
|
-
|
|
488
|
-
onWidgetError(event: any) {
|
|
489
|
-
console.error('❌ Widget error:', event.detail);
|
|
490
|
-
}
|
|
491
|
-
}
|
|
492
|
-
```
|
|
493
|
-
|
|
494
|
-
#### Alternative option: Programmatic creation
|
|
495
|
-
|
|
496
|
-
```typescript
|
|
497
|
-
// app.component.ts
|
|
498
|
-
import { Component, OnInit } from '@angular/core';
|
|
499
|
-
|
|
500
|
-
@Component({
|
|
501
|
-
selector: 'app-root',
|
|
502
|
-
template: `
|
|
503
|
-
<h1>My Angular Application</h1>
|
|
504
|
-
<button (click)="createWidget()">Create Widget</button>
|
|
505
|
-
<div #widgetContainer></div>
|
|
506
|
-
`
|
|
507
|
-
})
|
|
508
|
-
export class AppComponent implements OnInit {
|
|
509
|
-
ngOnInit() {
|
|
510
|
-
this.createWidget();
|
|
511
|
-
}
|
|
512
|
-
|
|
513
|
-
createWidget() {
|
|
514
|
-
if (window.TiaGPC) {
|
|
515
|
-
window.TiaGPC.create({
|
|
516
|
-
token: 'your-license-token',
|
|
517
|
-
theme: 'auto',
|
|
518
|
-
language: 'en',
|
|
519
|
-
onReady: () => console.log('Widget ready'),
|
|
520
|
-
onError: (err: any) => console.error(err)
|
|
521
|
-
});
|
|
522
|
-
}
|
|
523
|
-
}
|
|
524
|
-
}
|
|
525
|
-
```
|
|
526
|
-
|
|
527
|
-
---
|
|
528
|
-
|
|
529
|
-
### 4. ASP.NET / ASPX
|
|
530
|
-
|
|
531
|
-
#### Option 1: In an ASPX page
|
|
532
|
-
|
|
533
|
-
```aspx
|
|
534
|
-
<%@ Page Language="C#" AutoEventWireup="true" %>
|
|
535
|
-
|
|
536
|
-
<!DOCTYPE html>
|
|
537
|
-
<html>
|
|
538
|
-
<head>
|
|
539
|
-
<title>TIA GPC Widget - ASP.NET</title>
|
|
540
|
-
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.css" />
|
|
541
|
-
</head>
|
|
542
|
-
<body>
|
|
543
|
-
<form id="form1" runat="server">
|
|
544
|
-
<h1>My ASP.NET Application</h1>
|
|
545
|
-
|
|
546
|
-
<!-- TIA GPC Widget -->
|
|
547
|
-
<tia-gpc-widget
|
|
548
|
-
token="<%= ConfigurationManager.AppSettings["TiaGpcToken"] %>"
|
|
549
|
-
theme="auto"
|
|
550
|
-
position="bottom-right"
|
|
551
|
-
language="en"
|
|
552
|
-
primary-color="#2563eb"
|
|
553
|
-
></tia-gpc-widget>
|
|
554
|
-
</form>
|
|
555
|
-
|
|
556
|
-
<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.js"></script>
|
|
557
|
-
<script>
|
|
558
|
-
// Optional events
|
|
559
|
-
document.querySelector('tia-gpc-widget').addEventListener('ready', function() {
|
|
560
|
-
console.log('TIA GPC Widget initialized');
|
|
561
|
-
});
|
|
562
|
-
</script>
|
|
563
|
-
</body>
|
|
564
|
-
</html>
|
|
565
|
-
```
|
|
566
|
-
|
|
567
|
-
#### Option 2: With Master Page
|
|
568
|
-
|
|
569
|
-
In your `Site.Master`:
|
|
570
|
-
|
|
571
|
-
```aspx
|
|
572
|
-
<head runat="server">
|
|
573
|
-
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.css" />
|
|
574
|
-
</head>
|
|
575
|
-
<body>
|
|
576
|
-
<asp:ContentPlaceHolder ID="MainContent" runat="server">
|
|
577
|
-
</asp:ContentPlaceHolder>
|
|
578
|
-
|
|
579
|
-
<!-- Global widget -->
|
|
580
|
-
<tia-gpc-widget
|
|
581
|
-
token="<%= GetTiaGpcToken() %>"
|
|
582
|
-
theme="auto"
|
|
583
|
-
language="en"
|
|
584
|
-
></tia-gpc-widget>
|
|
585
|
-
|
|
586
|
-
<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.js"></script>
|
|
587
|
-
</body>
|
|
588
|
-
```
|
|
589
|
-
|
|
590
|
-
In your `Site.Master.cs`:
|
|
591
|
-
|
|
592
|
-
```csharp
|
|
593
|
-
public partial class SiteMaster : MasterPage
|
|
594
|
-
{
|
|
595
|
-
protected string GetTiaGpcToken()
|
|
596
|
-
{
|
|
597
|
-
return ConfigurationManager.AppSettings["TiaGpcToken"];
|
|
598
|
-
}
|
|
599
|
-
}
|
|
600
|
-
```
|
|
601
|
-
|
|
602
|
-
#### Option 3: MVC / Razor
|
|
603
|
-
|
|
604
|
-
In your layout `_Layout.cshtml`:
|
|
605
|
-
|
|
606
|
-
```html
|
|
607
|
-
<!DOCTYPE html>
|
|
608
|
-
<html>
|
|
609
|
-
<head>
|
|
610
|
-
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.css" />
|
|
611
|
-
</head>
|
|
612
|
-
<body>
|
|
613
|
-
@RenderBody()
|
|
614
|
-
|
|
615
|
-
<!-- TIA GPC Widget -->
|
|
616
|
-
<tia-gpc-widget
|
|
617
|
-
token="@ViewBag.TiaGpcToken"
|
|
618
|
-
theme="auto"
|
|
619
|
-
language="en"
|
|
620
|
-
></tia-gpc-widget>
|
|
621
|
-
|
|
622
|
-
<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.js"></script>
|
|
623
|
-
</body>
|
|
624
|
-
</html>
|
|
625
|
-
```
|
|
626
|
-
|
|
627
|
-
In your `Controller`:
|
|
628
|
-
|
|
629
|
-
```csharp
|
|
630
|
-
public class HomeController : Controller
|
|
631
|
-
{
|
|
632
|
-
public ActionResult Index()
|
|
633
|
-
{
|
|
634
|
-
ViewBag.TiaGpcToken = ConfigurationManager.AppSettings["TiaGpcToken"];
|
|
635
|
-
return View();
|
|
636
|
-
}
|
|
637
|
-
}
|
|
638
|
-
```
|
|
639
|
-
|
|
640
|
-
---
|
|
641
|
-
|
|
642
|
-
### 5. Vue.js
|
|
643
|
-
|
|
644
|
-
#### Installation
|
|
645
|
-
|
|
646
|
-
```bash
|
|
647
|
-
npm install tia-gpc-widget
|
|
648
|
-
```
|
|
649
|
-
|
|
650
|
-
#### Configuration
|
|
651
|
-
|
|
652
|
-
In `main.js` or `main.ts`:
|
|
653
|
-
|
|
654
|
-
```javascript
|
|
655
|
-
import { createApp } from 'vue';
|
|
656
|
-
import App from './App.vue';
|
|
657
|
-
|
|
658
|
-
// Import the standalone widget
|
|
659
|
-
import 'tia-gpc-widget/dist/tia-gpc-widget.standalone.js';
|
|
660
|
-
import 'tia-gpc-widget/dist/tia-gpc-widget.standalone.css';
|
|
661
|
-
|
|
662
|
-
const app = createApp(App);
|
|
663
|
-
|
|
664
|
-
// Configure Vue to ignore custom elements
|
|
665
|
-
app.config.compilerOptions.isCustomElement = (tag) => tag === 'tia-gpc-widget';
|
|
666
|
-
|
|
667
|
-
app.mount('#app');
|
|
668
|
-
```
|
|
669
|
-
|
|
670
|
-
#### Usage in components
|
|
671
|
-
|
|
672
|
-
```vue
|
|
673
|
-
<template>
|
|
674
|
-
<div>
|
|
675
|
-
<h1>My Vue Application</h1>
|
|
676
|
-
|
|
677
|
-
<!-- TIA GPC Widget -->
|
|
678
|
-
<tia-gpc-widget
|
|
679
|
-
:token="widgetToken"
|
|
680
|
-
:theme="theme"
|
|
681
|
-
:language="language"
|
|
682
|
-
position="bottom-right"
|
|
683
|
-
@ready="onReady"
|
|
684
|
-
@error="onError"
|
|
685
|
-
></tia-gpc-widget>
|
|
686
|
-
</div>
|
|
687
|
-
</template>
|
|
688
|
-
|
|
689
|
-
<script setup>
|
|
690
|
-
import { ref, onMounted } from 'vue';
|
|
691
|
-
|
|
692
|
-
const widgetToken = ref('your-license-token');
|
|
693
|
-
const theme = ref('auto');
|
|
694
|
-
const language = ref('en');
|
|
695
|
-
|
|
696
|
-
const onReady = () => {
|
|
697
|
-
console.log('✅ TIA GPC Widget ready');
|
|
698
|
-
};
|
|
699
|
-
|
|
700
|
-
const onError = (event) => {
|
|
701
|
-
console.error('❌ Error:', event.detail);
|
|
702
|
-
};
|
|
703
|
-
|
|
704
|
-
onMounted(() => {
|
|
705
|
-
console.log('TiaGPC available:', window.TiaGPC);
|
|
706
|
-
});
|
|
707
|
-
</script>
|
|
708
|
-
```
|
|
709
|
-
|
|
710
|
-
---
|
|
711
|
-
|
|
712
|
-
### 6. Next.js
|
|
713
|
-
|
|
714
|
-
#### Installation
|
|
715
|
-
|
|
716
|
-
```bash
|
|
717
|
-
npm install tia-gpc-widget
|
|
718
|
-
```
|
|
719
|
-
|
|
720
|
-
#### Usage (with Client Component)
|
|
721
|
-
|
|
722
|
-
```jsx
|
|
723
|
-
// components/TiaWidget.jsx
|
|
724
|
-
'use client'; // ← Important: Client Component
|
|
725
|
-
|
|
726
|
-
import { useEffect } from 'react';
|
|
727
|
-
|
|
728
|
-
export default function TiaWidget() {
|
|
729
|
-
useEffect(() => {
|
|
730
|
-
// Import widget only on client side
|
|
731
|
-
import('tia-gpc-widget/dist/tia-gpc-widget.standalone.js');
|
|
732
|
-
}, []);
|
|
733
|
-
|
|
734
|
-
return (
|
|
735
|
-
<>
|
|
736
|
-
{/* CSS */}
|
|
737
|
-
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.css" />
|
|
738
|
-
|
|
739
|
-
{/* Widget */}
|
|
740
|
-
<tia-gpc-widget
|
|
741
|
-
token={process.env.NEXT_PUBLIC_TIA_GPC_TOKEN}
|
|
742
|
-
theme="auto"
|
|
743
|
-
language="en"
|
|
744
|
-
></tia-gpc-widget>
|
|
745
|
-
</>
|
|
746
|
-
);
|
|
747
|
-
}
|
|
748
|
-
```
|
|
749
|
-
|
|
750
|
-
In your page:
|
|
751
|
-
|
|
752
|
-
```jsx
|
|
753
|
-
// app/page.jsx
|
|
754
|
-
import TiaWidget from '@/components/TiaWidget';
|
|
755
|
-
|
|
756
|
-
export default function Home() {
|
|
757
|
-
return (
|
|
758
|
-
<main>
|
|
759
|
-
<h1>My Next.js App</h1>
|
|
760
|
-
<TiaWidget />
|
|
761
|
-
</main>
|
|
762
|
-
);
|
|
763
|
-
}
|
|
764
|
-
```
|
|
765
|
-
|
|
766
|
-
---
|
|
767
|
-
|
|
768
|
-
### 7. PHP
|
|
769
|
-
|
|
770
|
-
```php
|
|
771
|
-
<!DOCTYPE html>
|
|
772
|
-
<html lang="en">
|
|
773
|
-
<head>
|
|
774
|
-
<meta charset="UTF-8">
|
|
775
|
-
<title>TIA GPC Widget - PHP</title>
|
|
776
|
-
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.css">
|
|
777
|
-
</head>
|
|
778
|
-
<body>
|
|
779
|
-
<h1>My PHP Application</h1>
|
|
780
|
-
|
|
781
|
-
<?php
|
|
782
|
-
// Get token from environment variables or config
|
|
783
|
-
$tiaGpcToken = getenv('TIA_GPC_TOKEN') ?: 'your-license-token';
|
|
784
|
-
$userLanguage = $_SESSION['user_language'] ?? 'en';
|
|
785
|
-
?>
|
|
786
|
-
|
|
787
|
-
<!-- TIA GPC Widget -->
|
|
788
|
-
<tia-gpc-widget
|
|
789
|
-
token="<?php echo htmlspecialchars($tiaGpcToken); ?>"
|
|
790
|
-
theme="auto"
|
|
791
|
-
position="bottom-right"
|
|
792
|
-
language="<?php echo htmlspecialchars($userLanguage); ?>"
|
|
793
|
-
></tia-gpc-widget>
|
|
794
|
-
|
|
795
|
-
<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.js"></script>
|
|
796
|
-
</body>
|
|
797
|
-
</html>
|
|
798
|
-
```
|
|
799
|
-
|
|
800
|
-
---
|
|
801
|
-
|
|
802
|
-
## 🎛️ API & Configuration
|
|
803
|
-
|
|
804
|
-
### Props/Attributes
|
|
805
|
-
|
|
806
|
-
All frameworks support the same attributes:
|
|
807
|
-
|
|
808
|
-
| Attribute | Type | Default | Description |
|
|
809
|
-
|----------|------|-------------|-------------|
|
|
810
|
-
| `token` | `string` | **Required** | TIA GPC license token |
|
|
811
|
-
| `theme` | `'auto' \| 'light' \| 'dark'` | `'auto'` | Widget theme |
|
|
812
|
-
| `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | Screen position |
|
|
813
|
-
| `language` | `'es' \| 'en' \| 'fr'` | `'es'` | Widget language |
|
|
814
|
-
| `primary-color` | `string` | `'#2563eb'` | Primary color (hexadecimal) |
|
|
815
|
-
| `width` | `string` | `'400px'` | Widget width |
|
|
816
|
-
| `height` | `string` | `'600px'` | Widget height |
|
|
817
|
-
| `api-url` | `string` | Default API | Custom API URL |
|
|
818
|
-
| `turnstile-site-key` | `string` | - | Cloudflare Turnstile site key |
|
|
819
|
-
| `auto-open` | `boolean` | `false` | Auto-open on load |
|
|
820
|
-
| `show-branding` | `boolean` | `true` | Show TIA GPC branding |
|
|
821
|
-
| `mobile-fullscreen` | `boolean` | `true` | Fullscreen on mobile |
|
|
822
|
-
|
|
823
|
-
### Events
|
|
824
|
-
|
|
825
|
-
| Event | Description | Payload |
|
|
826
|
-
|--------|-------------|---------|
|
|
827
|
-
| `ready` | Fired when widget is ready | - |
|
|
828
|
-
| `error` | Fired when an error occurs | `{ detail: ErrorObject }` |
|
|
829
|
-
| `close` | Fired when widget closes | - |
|
|
830
|
-
|
|
831
|
-
#### Event usage example
|
|
832
|
-
|
|
833
|
-
```html
|
|
834
|
-
<script>
|
|
835
|
-
const widget = document.querySelector('tia-gpc-widget');
|
|
836
|
-
|
|
837
|
-
widget.addEventListener('ready', () => {
|
|
838
|
-
console.log('Widget ready');
|
|
839
|
-
});
|
|
840
|
-
|
|
841
|
-
widget.addEventListener('error', (e) => {
|
|
842
|
-
console.error('Error:', e.detail);
|
|
843
|
-
// Send to logging system
|
|
844
|
-
});
|
|
845
|
-
|
|
846
|
-
widget.addEventListener('close', () => {
|
|
847
|
-
console.log('User closed the widget');
|
|
848
|
-
// Analytics or tracking
|
|
849
|
-
});
|
|
850
|
-
</script>
|
|
851
|
-
```
|
|
852
|
-
|
|
853
|
-
### Programmatic API (JavaScript)
|
|
854
|
-
|
|
855
|
-
The widget exposes a global `TiaGPC` API for programmatic control:
|
|
856
|
-
|
|
857
|
-
```javascript
|
|
858
|
-
// Create widget programmatically
|
|
859
|
-
const widget = TiaGPC.create({
|
|
860
|
-
token: 'your-token',
|
|
861
|
-
theme: 'dark',
|
|
862
|
-
language: 'en',
|
|
863
|
-
position: TiaGPC.POSITIONS.BOTTOM_LEFT,
|
|
864
|
-
onReady: () => console.log('Ready'),
|
|
865
|
-
onError: (err) => console.error(err)
|
|
866
|
-
});
|
|
867
|
-
|
|
868
|
-
// Open widget
|
|
869
|
-
widget.open();
|
|
870
|
-
|
|
871
|
-
// Close widget
|
|
872
|
-
widget.close();
|
|
873
|
-
|
|
874
|
-
// View information
|
|
875
|
-
TiaGPC.info();
|
|
876
|
-
|
|
877
|
-
// Available constants
|
|
878
|
-
console.log(TiaGPC.POSITIONS); // { BOTTOM_RIGHT, BOTTOM_LEFT, ... }
|
|
879
|
-
console.log(TiaGPC.THEMES); // { AUTO, LIGHT, DARK }
|
|
880
|
-
console.log(TiaGPC.LANGUAGES); // { ES, EN, FR }
|
|
881
|
-
```
|
|
882
|
-
|
|
883
|
-
---
|
|
884
|
-
|
|
885
|
-
## 🎨 Customization
|
|
886
|
-
|
|
887
|
-
### Themes
|
|
888
|
-
|
|
889
|
-
```html
|
|
890
|
-
<!-- Automatic (follows system preferences) -->
|
|
891
|
-
<tia-gpc-widget theme="auto"></tia-gpc-widget>
|
|
892
|
-
|
|
893
|
-
<!-- Light -->
|
|
894
|
-
<tia-gpc-widget theme="light"></tia-gpc-widget>
|
|
895
|
-
|
|
896
|
-
<!-- Dark -->
|
|
897
|
-
<tia-gpc-widget theme="dark"></tia-gpc-widget>
|
|
898
|
-
```
|
|
899
|
-
|
|
900
|
-
### Positions
|
|
901
|
-
|
|
902
|
-
```html
|
|
903
|
-
<!-- Bottom right corner (default) -->
|
|
904
|
-
<tia-gpc-widget position="bottom-right"></tia-gpc-widget>
|
|
905
|
-
|
|
906
|
-
<!-- Bottom left corner -->
|
|
907
|
-
<tia-gpc-widget position="bottom-left"></tia-gpc-widget>
|
|
908
|
-
|
|
909
|
-
<!-- Top right corner -->
|
|
910
|
-
<tia-gpc-widget position="top-right"></tia-gpc-widget>
|
|
911
|
-
|
|
912
|
-
<!-- Top left corner -->
|
|
913
|
-
<tia-gpc-widget position="top-left"></tia-gpc-widget>
|
|
914
|
-
```
|
|
915
|
-
|
|
916
|
-
### Languages
|
|
917
|
-
|
|
918
|
-
```html
|
|
919
|
-
<!-- Spanish -->
|
|
920
|
-
<tia-gpc-widget language="es"></tia-gpc-widget>
|
|
921
|
-
|
|
922
|
-
<!-- English -->
|
|
923
|
-
<tia-gpc-widget language="en"></tia-gpc-widget>
|
|
924
|
-
|
|
925
|
-
<!-- French -->
|
|
926
|
-
<tia-gpc-widget language="fr"></tia-gpc-widget>
|
|
927
|
-
```
|
|
928
|
-
|
|
929
|
-
### Colors
|
|
930
|
-
|
|
931
|
-
```html
|
|
932
|
-
<!-- Custom color -->
|
|
933
|
-
<tia-gpc-widget
|
|
934
|
-
primary-color="#10b981"
|
|
935
|
-
></tia-gpc-widget>
|
|
936
|
-
|
|
937
|
-
<!-- Blue (default) -->
|
|
938
|
-
<tia-gpc-widget primary-color="#2563eb"></tia-gpc-widget>
|
|
939
|
-
|
|
940
|
-
<!-- Green -->
|
|
941
|
-
<tia-gpc-widget primary-color="#16a34a"></tia-gpc-widget>
|
|
942
|
-
|
|
943
|
-
<!-- Purple -->
|
|
944
|
-
<tia-gpc-widget primary-color="#9333ea"></tia-gpc-widget>
|
|
945
|
-
```
|
|
946
|
-
|
|
947
|
-
---
|
|
948
|
-
|
|
949
|
-
## 🛠️ Build & Development
|
|
950
|
-
|
|
951
|
-
### Available scripts
|
|
952
|
-
|
|
953
|
-
```bash
|
|
954
|
-
# Development (dev mode with hot reload)
|
|
955
|
-
npm run dev
|
|
956
|
-
|
|
957
|
-
# Complete build (NPM + Standalone)
|
|
958
|
-
npm run build
|
|
959
|
-
|
|
960
|
-
# Build only for NPM (without bundled React)
|
|
961
|
-
npm run build:npm
|
|
962
|
-
|
|
963
|
-
# Standalone build (with bundled React)
|
|
964
|
-
npm run build:standalone
|
|
965
|
-
|
|
966
|
-
# Lint
|
|
967
|
-
npm run lint
|
|
968
|
-
|
|
969
|
-
# Preview
|
|
970
|
-
npm run preview
|
|
971
|
-
```
|
|
972
|
-
|
|
973
|
-
### Generated file structure
|
|
974
|
-
|
|
975
|
-
```
|
|
976
|
-
dist/
|
|
977
|
-
├── tia-gpc.es.js # ESM build for NPM
|
|
978
|
-
├── tia-gpc.cjs.js # CommonJS build for NPM
|
|
979
|
-
├── tia-gpc.css # CSS for NPM build
|
|
980
|
-
├── tia-gpc-widget.standalone.js # Standalone build (IIFE with React)
|
|
981
|
-
└── tia-gpc-widget.standalone.css # CSS for standalone
|
|
982
|
-
```
|
|
983
|
-
|
|
984
|
-
### Which file to use?
|
|
985
|
-
|
|
986
|
-
| Environment | File to use |
|
|
987
|
-
|---------|----------------|
|
|
988
|
-
| React, Vue (with build system) | `tia-gpc.es.js` + `tia-gpc.css` |
|
|
989
|
-
| Node.js CommonJS | `tia-gpc.cjs.js` + `tia-gpc.css` |
|
|
990
|
-
| Plain HTML, Angular, ASP.NET, PHP | `tia-gpc-widget.standalone.js` + `tia-gpc-widget.standalone.css` |
|
|
991
|
-
|
|
992
|
-
---
|
|
993
|
-
|
|
994
|
-
## 📤 Publishing
|
|
995
|
-
|
|
996
|
-
### Publish to NPM (Public)
|
|
997
|
-
|
|
998
|
-
```bash
|
|
999
|
-
# 1. Login to NPM
|
|
1000
|
-
npm login
|
|
1001
|
-
|
|
1002
|
-
# 2. Build the project
|
|
1003
|
-
npm run build
|
|
1004
|
-
|
|
1005
|
-
# 3. Publish
|
|
1006
|
-
npm publish
|
|
1007
|
-
```
|
|
1008
|
-
|
|
1009
|
-
### Publish to Private NPM / GitLab Package Registry
|
|
1010
|
-
|
|
1011
|
-
#### Configure `.npmrc`
|
|
1012
|
-
|
|
1013
|
-
Create an `.npmrc` file in the project root:
|
|
1014
|
-
|
|
1015
|
-
```ini
|
|
1016
|
-
# For GitLab Package Registry
|
|
1017
|
-
@your-scope:registry=https://gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/
|
|
1018
|
-
//gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/:_authToken=${CI_JOB_TOKEN}
|
|
1019
|
-
```
|
|
1020
|
-
|
|
1021
|
-
#### Update `package.json`
|
|
1022
|
-
|
|
1023
|
-
```json
|
|
1024
|
-
{
|
|
1025
|
-
"name": "@your-scope/tia-gpc-widget",
|
|
1026
|
-
"publishConfig": {
|
|
1027
|
-
"@your-scope:registry": "https://gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/"
|
|
1028
|
-
}
|
|
1029
|
-
}
|
|
1030
|
-
```
|
|
1031
|
-
|
|
1032
|
-
#### Publish
|
|
1033
|
-
|
|
1034
|
-
```bash
|
|
1035
|
-
npm run build
|
|
1036
|
-
npm publish
|
|
1037
|
-
```
|
|
1038
|
-
|
|
1039
|
-
### CDN Distribution
|
|
1040
|
-
|
|
1041
|
-
After publishing to npm, your package is automatically available on these CDNs:
|
|
1042
|
-
|
|
1043
|
-
#### jsDelivr
|
|
1044
|
-
```html
|
|
1045
|
-
<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.js"></script>
|
|
1046
|
-
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.css">
|
|
1047
|
-
```
|
|
1048
|
-
|
|
1049
|
-
#### unpkg
|
|
1050
|
-
```html
|
|
1051
|
-
<script src="https://unpkg.com/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.js"></script>
|
|
1052
|
-
<link rel="stylesheet" href="https://unpkg.com/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.css">
|
|
1053
|
-
```
|
|
1054
|
-
|
|
1055
|
-
**Note:** CDNs may take 5-10 minutes to sync after publishing to npm.
|
|
1056
|
-
|
|
1057
|
-
### Manual Distribution
|
|
1058
|
-
|
|
1059
|
-
Copy files from `dist/` to your web server:
|
|
1060
|
-
|
|
1061
|
-
```bash
|
|
1062
|
-
# Copy standalone files to server
|
|
1063
|
-
cp dist/tia-gpc-widget.standalone.* /var/www/html/assets/
|
|
1064
|
-
```
|
|
1065
|
-
|
|
1066
|
-
---
|
|
1067
|
-
|
|
1068
|
-
## 🔐 Getting a License Token
|
|
1069
|
-
|
|
1070
|
-
To use this widget you need a TIA GPC license token. Contact the TIA team to get your token:
|
|
1071
|
-
|
|
1072
|
-
- **Email**: support@tia.com
|
|
1073
|
-
- **Web**: https://tia.com/gpc
|
|
1074
|
-
|
|
1075
|
-
---
|
|
1076
|
-
|
|
1077
|
-
## 📊 Bundle Sizes
|
|
1078
|
-
|
|
1079
|
-
| File | Size (gzip) | Description |
|
|
1080
|
-
|---------|---------------|-------------|
|
|
1081
|
-
| `tia-gpc.es.js` | ~45 KB | NPM build (without React) |
|
|
1082
|
-
| `tia-gpc-widget.standalone.js` | ~180 KB | Standalone build (with React) |
|
|
1083
|
-
| `*.css` | ~15 KB | Styles |
|
|
1084
|
-
|
|
1085
|
-
The standalone bundle is larger because it includes React and all dependencies.
|
|
1086
|
-
|
|
1087
|
-
---
|
|
1088
|
-
|
|
1089
|
-
## 🐛 Troubleshooting
|
|
1090
|
-
|
|
1091
|
-
### Widget doesn't appear
|
|
1092
|
-
|
|
1093
|
-
1. Verify you included both files (JS and CSS)
|
|
1094
|
-
2. Check browser console for errors
|
|
1095
|
-
3. Make sure the token is valid
|
|
1096
|
-
|
|
1097
|
-
### Error: "customElements.define() called with incorrect arguments"
|
|
1098
|
-
|
|
1099
|
-
- In Angular: Add `CUSTOM_ELEMENTS_SCHEMA` to your module
|
|
1100
|
-
- In Vue: Configure `isCustomElement` in compiler options
|
|
1101
|
-
|
|
1102
|
-
### CSS Conflicts
|
|
1103
|
-
|
|
1104
|
-
The widget uses `gpc-` prefixes on all classes to avoid conflicts. If there are still issues, you can increase specificity:
|
|
1105
|
-
|
|
1106
|
-
```css
|
|
1107
|
-
.your-container tia-gpc-widget {
|
|
1108
|
-
/* your custom styles */
|
|
1109
|
-
}
|
|
1110
|
-
```
|
|
1111
|
-
|
|
1112
|
-
### React is not defined (in standalone build)
|
|
1113
|
-
|
|
1114
|
-
If you see this error, make sure you're using the `standalone.js` file and not the regular NPM build.
|
|
1115
|
-
|
|
1116
|
-
---
|
|
1117
|
-
|
|
1118
|
-
## 📝 License
|
|
1119
|
-
|
|
1120
|
-
UNLICENSED - Internal use by TIA
|
|
1121
|
-
|
|
1122
|
-
---
|
|
1123
|
-
|
|
1124
|
-
## 👥 Support
|
|
1125
|
-
|
|
1126
|
-
For technical support:
|
|
1127
|
-
|
|
1128
|
-
- **Email**: support@tia.com
|
|
1129
|
-
- **GitLab Issues**: https://gitlab.com/softia/tiagpc-frontend/issues
|
|
1130
|
-
- **Documentation**: This README
|
|
1131
|
-
|
|
1132
|
-
---
|
|
1133
|
-
|
|
1134
|
-
## 🚀 Changelog
|
|
1135
|
-
|
|
1136
|
-
### v1.0.6 (2025-01-11)
|
|
1137
|
-
|
|
1138
|
-
- ✨ Added CDN support via jsDelivr and unpkg
|
|
1139
|
-
- 📝 Updated documentation to English
|
|
1140
|
-
- 🔧 Added `unpkg` and `jsdelivr` fields to package.json
|
|
1141
|
-
|
|
1142
|
-
### v1.0.0 (2025-01-10)
|
|
1143
|
-
|
|
1144
|
-
- ✨ Initial release
|
|
1145
|
-
- ✅ React support
|
|
1146
|
-
- ✅ Standalone build for HTML/Angular/ASP.NET
|
|
1147
|
-
- ✅ Web Component API
|
|
1148
|
-
- ✅ Light/dark themes
|
|
1149
|
-
- ✅ Internationalization (ES/EN/FR)
|
|
1150
|
-
- ✅ Full customization
|
|
1151
|
-
|
|
1152
|
-
---
|
|
1153
|
-
|
|
1154
|
-
## 📚 Loader Advanced Usage
|
|
1155
|
-
|
|
1156
|
-
### What is the Auto-Update Loader?
|
|
1157
|
-
|
|
1158
|
-
The **TIA GPC Widget Loader** is a revolutionary approach to widget distribution that solves the update problem:
|
|
1159
|
-
|
|
1160
|
-
- **Traditional approach**: Clients must manually update the version number in their code every time you release
|
|
1161
|
-
- **Loader approach**: Clients install once, you control which version they receive via `version.json`
|
|
1162
|
-
|
|
1163
|
-
### How it Works
|
|
1164
|
-
|
|
1165
|
-
1. **Client installs the loader** (one time only):
|
|
1166
|
-
```html
|
|
1167
|
-
<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@latest/dist/loader.min.js"></script>
|
|
1168
|
-
```
|
|
1169
|
-
|
|
1170
|
-
2. **Loader fetches** `version.json` to determine which widget version to load
|
|
1171
|
-
|
|
1172
|
-
3. **Loader dynamically loads** the appropriate widget version
|
|
1173
|
-
|
|
1174
|
-
4. **You publish a new version**:
|
|
1175
|
-
```bash
|
|
1176
|
-
npm run build # Automatically updates version.json
|
|
1177
|
-
npm publish
|
|
1178
|
-
```
|
|
1179
|
-
|
|
1180
|
-
5. **All clients automatically receive the new version** (within minutes, when CDN syncs)
|
|
1181
|
-
|
|
1182
|
-
### Configuration Options
|
|
1183
|
-
|
|
1184
|
-
#### Loader Attributes
|
|
1185
|
-
|
|
1186
|
-
| Attribute | Type | Default | Description |
|
|
1187
|
-
|-----------|------|---------|-------------|
|
|
1188
|
-
| `data-channel` | `'stable' \| 'beta'` | `'stable'` | Distribution channel |
|
|
1189
|
-
| `data-version` | `string` | `null` | Pin to specific version (disables auto-update) |
|
|
1190
|
-
| `data-debug` | `boolean` | `false` | Enable debug logging |
|
|
1191
|
-
| `data-api-url` | `string` | `null` | Analytics endpoint URL |
|
|
1192
|
-
|
|
1193
|
-
#### Examples
|
|
1194
|
-
|
|
1195
|
-
**Use beta channel:**
|
|
1196
|
-
```html
|
|
1197
|
-
<script
|
|
1198
|
-
src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@latest/dist/loader.min.js"
|
|
1199
|
-
data-channel="beta"
|
|
1200
|
-
></script>
|
|
1201
|
-
```
|
|
1202
|
-
|
|
1203
|
-
**Pin to specific version (no auto-update):**
|
|
1204
|
-
```html
|
|
1205
|
-
<script
|
|
1206
|
-
src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@latest/dist/loader.min.js"
|
|
1207
|
-
data-version="1.0.8"
|
|
1208
|
-
></script>
|
|
1209
|
-
```
|
|
1210
|
-
|
|
1211
|
-
**Enable debug mode:**
|
|
1212
|
-
```html
|
|
1213
|
-
<script
|
|
1214
|
-
src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@latest/dist/loader.min.js"
|
|
1215
|
-
data-debug="true"
|
|
1216
|
-
></script>
|
|
1217
|
-
```
|
|
1218
|
-
|
|
1219
|
-
### Loader Events
|
|
1220
|
-
|
|
1221
|
-
The loader emits custom events you can listen to:
|
|
1222
|
-
|
|
1223
|
-
```javascript
|
|
1224
|
-
// Widget loaded successfully
|
|
1225
|
-
window.addEventListener('tia-gpc-loader-ready', (event) => {
|
|
1226
|
-
console.log('Widget loaded:', event.detail);
|
|
1227
|
-
// event.detail = {
|
|
1228
|
-
// version: "1.0.9",
|
|
1229
|
-
// loadTime: 1234, // milliseconds
|
|
1230
|
-
// attempts: 1,
|
|
1231
|
-
// channel: "stable"
|
|
1232
|
-
// }
|
|
1233
|
-
});
|
|
1234
|
-
|
|
1235
|
-
// Widget failed to load
|
|
1236
|
-
window.addEventListener('tia-gpc-loader-error', (event) => {
|
|
1237
|
-
console.error('Widget error:', event.detail);
|
|
1238
|
-
// event.detail = {
|
|
1239
|
-
// error: "Failed to load...",
|
|
1240
|
-
// attempts: 3,
|
|
1241
|
-
// version: "1.0.9"
|
|
1242
|
-
// }
|
|
1243
|
-
});
|
|
1244
|
-
```
|
|
1245
|
-
|
|
1246
|
-
### Loader API
|
|
1247
|
-
|
|
1248
|
-
The loader exposes a global `TiaGPCLoader` object:
|
|
1249
|
-
|
|
1250
|
-
```javascript
|
|
1251
|
-
// Get loader version
|
|
1252
|
-
console.log(window.TiaGPCLoader.version); // "1.0.0"
|
|
1253
|
-
|
|
1254
|
-
// Reload widget
|
|
1255
|
-
window.TiaGPCLoader.reload();
|
|
1256
|
-
|
|
1257
|
-
// Get configuration
|
|
1258
|
-
console.log(window.TiaGPCLoader.config);
|
|
1259
|
-
```
|
|
1260
|
-
|
|
1261
|
-
### Version Control with version.json
|
|
1262
|
-
|
|
1263
|
-
The `version.json` file controls which version is served to clients:
|
|
1264
|
-
|
|
1265
|
-
```json
|
|
1266
|
-
{
|
|
1267
|
-
"version": "1.0.9",
|
|
1268
|
-
"stable": {
|
|
1269
|
-
"version": "1.0.9",
|
|
1270
|
-
"js": "https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.9/dist/tia-gpc-widget.standalone.js",
|
|
1271
|
-
"css": "https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.9/dist/tia-gpc-widget.standalone.css",
|
|
1272
|
-
"cdn": "jsdelivr"
|
|
1273
|
-
},
|
|
1274
|
-
"beta": {
|
|
1275
|
-
"version": "1.1.0-beta",
|
|
1276
|
-
"js": "https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.1.0-beta/dist/tia-gpc-widget.standalone.js",
|
|
1277
|
-
"css": "https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.1.0-beta/dist/tia-gpc-widget.standalone.css",
|
|
1278
|
-
"cdn": "jsdelivr"
|
|
1279
|
-
}
|
|
1280
|
-
}
|
|
1281
|
-
```
|
|
1282
|
-
|
|
1283
|
-
This file is automatically generated when you run `npm run build`.
|
|
1284
|
-
|
|
1285
|
-
### Deployment Workflow
|
|
1286
|
-
|
|
1287
|
-
#### Before (without loader):
|
|
1288
|
-
```bash
|
|
1289
|
-
# 1. Make changes to widget
|
|
1290
|
-
# 2. Build
|
|
1291
|
-
npm run build
|
|
1292
|
-
|
|
1293
|
-
# 3. Publish to npm
|
|
1294
|
-
npm publish
|
|
1295
|
-
|
|
1296
|
-
# ❌ Clients must manually update their code:
|
|
1297
|
-
# <script src="...@1.0.6/..."></script> → <script src="...@1.0.7/..."></script>
|
|
1298
|
-
```
|
|
1299
|
-
|
|
1300
|
-
#### After (with loader):
|
|
1301
|
-
```bash
|
|
1302
|
-
# 1. Make changes to widget
|
|
1303
|
-
# 2. Build (automatically updates version.json)
|
|
1304
|
-
npm run build
|
|
1305
|
-
|
|
1306
|
-
# 3. Publish to npm
|
|
1307
|
-
npm publish
|
|
1308
|
-
|
|
1309
|
-
# ✅ All clients automatically receive the new version!
|
|
1310
|
-
# No manual updates required!
|
|
1311
|
-
```
|
|
1312
|
-
|
|
1313
|
-
### Advanced: Gradual Rollout
|
|
1314
|
-
|
|
1315
|
-
You can manually edit `version.json` to implement gradual rollouts:
|
|
1316
|
-
|
|
1317
|
-
```json
|
|
1318
|
-
{
|
|
1319
|
-
"stable": {
|
|
1320
|
-
"version": "1.0.9",
|
|
1321
|
-
"rollout": {
|
|
1322
|
-
"percentage": 50, // Only 50% of users get this version
|
|
1323
|
-
"whitelist": ["client-id-1", "client-id-2"],
|
|
1324
|
-
"blacklist": ["problematic-client"]
|
|
1325
|
-
}
|
|
1326
|
-
}
|
|
1327
|
-
}
|
|
1328
|
-
```
|
|
1329
|
-
|
|
1330
|
-
Note: Rollout logic must be implemented on your backend.
|
|
1331
|
-
|
|
1332
|
-
### Migration Guide
|
|
1333
|
-
|
|
1334
|
-
#### Migrating from Direct CDN Links
|
|
1335
|
-
|
|
1336
|
-
**Before:**
|
|
1337
|
-
```html
|
|
1338
|
-
<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.js"></script>
|
|
1339
|
-
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.css">
|
|
1340
|
-
|
|
1341
|
-
<tia-gpc-widget token="xxx"></tia-gpc-widget>
|
|
1342
|
-
```
|
|
1343
|
-
|
|
1344
|
-
**After:**
|
|
1345
|
-
```html
|
|
1346
|
-
<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@latest/dist/loader.min.js"></script>
|
|
1347
|
-
|
|
1348
|
-
<tia-gpc-widget token="xxx"></tia-gpc-widget>
|
|
1349
|
-
```
|
|
1350
|
-
|
|
1351
|
-
That's it! The loader handles everything else.
|
|
1352
|
-
|
|
1353
|
-
### Troubleshooting
|
|
1354
|
-
|
|
1355
|
-
#### Loader not loading widget
|
|
1356
|
-
|
|
1357
|
-
1. Open browser console and check for errors
|
|
1358
|
-
2. Enable debug mode: `data-debug="true"`
|
|
1359
|
-
3. Check network tab for failed requests
|
|
1360
|
-
4. Verify `version.json` is accessible
|
|
1361
|
-
|
|
1362
|
-
#### Widget not updating
|
|
1363
|
-
|
|
1364
|
-
1. Clear browser cache
|
|
1365
|
-
2. Check that `version.json` has the correct version
|
|
1366
|
-
3. Wait for CDN to sync (can take 5-10 minutes)
|
|
1367
|
-
4. Check if client is using `data-version` (which pins to specific version)
|
|
1368
|
-
|
|
1369
|
-
#### Using with Content Security Policy (CSP)
|
|
1370
|
-
|
|
1371
|
-
If your site uses CSP, you may need to add:
|
|
1372
|
-
|
|
1373
|
-
```html
|
|
1374
|
-
<meta http-equiv="Content-Security-Policy" content="
|
|
1375
|
-
script-src 'self' https://cdn.jsdelivr.net https://unpkg.com;
|
|
1376
|
-
style-src 'self' https://cdn.jsdelivr.net https://unpkg.com;
|
|
1377
|
-
connect-src 'self' https://cdn.jsdelivr.net https://unpkg.com;
|
|
1378
|
-
">
|
|
1379
|
-
```
|
|
1380
|
-
|
|
1381
|
-
### Examples
|
|
1382
|
-
|
|
1383
|
-
See complete examples in the `/examples` folder:
|
|
1384
|
-
- `examples/loader-usage.html` - Complete loader demo with all features
|
|
1385
|
-
|
|
1386
|
-
---
|
|
1387
|
-
|
|
1388
|
-
**Built with ❤️ by the TIA team**
|
|
1
|
+
# TIA GPC Widget
|
|
2
|
+
|
|
3
|
+
Intelligent chat widget for TIA GPC integration. Compatible with **React, HTML, Angular, ASP.NET, Vue, and any other framework**.
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/tia-gpc-widget)
|
|
6
|
+
[](https://www.jsdelivr.com/package/npm/tia-gpc-widget)
|
|
7
|
+
[](LICENSE)
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## 📋 Table of Contents
|
|
12
|
+
|
|
13
|
+
- [Features](#-features)
|
|
14
|
+
- [Installation](#-installation)
|
|
15
|
+
- [Option 1: NPM (For React/Node Projects)](#option-1-npm-for-reactnode-projects)
|
|
16
|
+
- [Option 2: CDN (For HTML, Angular, ASP.NET, etc.)](#option-2-cdn-for-html-angular-aspnet-etc)
|
|
17
|
+
- [Quick Start](#-quick-start)
|
|
18
|
+
- [Framework Examples](#-framework-examples)
|
|
19
|
+
- [React](#1-react)
|
|
20
|
+
- [HTML / Vanilla JavaScript](#2-html--vanilla-javascript)
|
|
21
|
+
- [Angular](#3-angular)
|
|
22
|
+
- [ASP.NET / ASPX](#4-aspnet--aspx)
|
|
23
|
+
- [Vue.js](#5-vuejs)
|
|
24
|
+
- [Next.js](#6-nextjs)
|
|
25
|
+
- [PHP](#7-php)
|
|
26
|
+
- [API & Configuration](#-api--configuration)
|
|
27
|
+
- [Props/Attributes](#propsattributes)
|
|
28
|
+
- [Events](#events)
|
|
29
|
+
- [Programmatic API (JavaScript)](#programmatic-api-javascript)
|
|
30
|
+
- [Customization](#-customization)
|
|
31
|
+
- [Themes](#themes)
|
|
32
|
+
- [Positions](#positions)
|
|
33
|
+
- [Languages](#languages)
|
|
34
|
+
- [Colors](#colors)
|
|
35
|
+
- [Build & Development](#-build--development)
|
|
36
|
+
- [Publishing](#-publishing)
|
|
37
|
+
- [Support](#-support)
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## 🚀 Features
|
|
42
|
+
|
|
43
|
+
- ✅ **Framework Agnostic**: Works in React, Angular, Vue, ASP.NET, plain HTML, etc.
|
|
44
|
+
- ✅ **Web Component**: Based on native web standards
|
|
45
|
+
- ✅ **Themes**: Light, dark, or automatic mode
|
|
46
|
+
- ✅ **Internationalization**: Spanish, English, French
|
|
47
|
+
- ✅ **Responsive**: Adaptive design for mobile and desktop
|
|
48
|
+
- ✅ **Customizable**: Colors, positions, dimensions
|
|
49
|
+
- ✅ **TypeScript Ready**: Types included
|
|
50
|
+
- ✅ **Zero Dependencies**: Standalone bundle includes everything needed
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## 🚀 Auto-Update Loader (Recommended)
|
|
55
|
+
|
|
56
|
+
**NEW!** Install once, get updates forever. No more manual version updates!
|
|
57
|
+
|
|
58
|
+
The **TIA GPC Widget Loader** is a small, stable script (~1KB gzipped) that automatically loads the latest version of the widget. Your clients install it **ONCE** and receive all future updates automatically.
|
|
59
|
+
|
|
60
|
+
### Quick Start with Loader
|
|
61
|
+
|
|
62
|
+
```html
|
|
63
|
+
<!DOCTYPE html>
|
|
64
|
+
<html lang="en">
|
|
65
|
+
<head>
|
|
66
|
+
<meta charset="UTF-8">
|
|
67
|
+
<title>My App with TIA GPC</title>
|
|
68
|
+
</head>
|
|
69
|
+
<body>
|
|
70
|
+
<h1>My Application</h1>
|
|
71
|
+
|
|
72
|
+
<!-- TIA GPC Widget Loader (install once, updates forever) -->
|
|
73
|
+
<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@latest/dist/loader.min.js"></script>
|
|
74
|
+
|
|
75
|
+
<!-- Widget element -->
|
|
76
|
+
<tia-gpc-widget
|
|
77
|
+
token="your-license-token-here"
|
|
78
|
+
theme="auto"
|
|
79
|
+
position="bottom-right"
|
|
80
|
+
language="en"
|
|
81
|
+
></tia-gpc-widget>
|
|
82
|
+
</body>
|
|
83
|
+
</html>
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
**Benefits:**
|
|
87
|
+
- ✅ Install once, never update manually again
|
|
88
|
+
- ✅ Automatic updates when you publish new versions
|
|
89
|
+
- ✅ Built-in error handling and retries
|
|
90
|
+
- ✅ Support for stable/beta channels
|
|
91
|
+
- ✅ Extremely small (~1KB gzipped)
|
|
92
|
+
- ✅ Works with all frameworks (HTML, React, Angular, ASP.NET, etc.)
|
|
93
|
+
|
|
94
|
+
[See complete loader documentation and examples →](#loader-advanced-usage)
|
|
95
|
+
|
|
96
|
+
---
|
|
97
|
+
|
|
98
|
+
## 📦 Installation
|
|
99
|
+
|
|
100
|
+
### Option 1: Auto-Update Loader (Recommended)
|
|
101
|
+
|
|
102
|
+
Use the loader for automatic updates:
|
|
103
|
+
|
|
104
|
+
```html
|
|
105
|
+
<!-- jsDelivr (Recommended) -->
|
|
106
|
+
<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@latest/dist/loader.min.js"></script>
|
|
107
|
+
|
|
108
|
+
<!-- unpkg -->
|
|
109
|
+
<script src="https://unpkg.com/tia-gpc-widget@latest/dist/loader.min.js"></script>
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Then use the widget as normal:
|
|
113
|
+
```html
|
|
114
|
+
<tia-gpc-widget token="your-token" theme="auto"></tia-gpc-widget>
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
### Option 2: NPM (For React/Node Projects)
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
npm install tia-gpc-widget
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
or with yarn:
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
yarn add tia-gpc-widget
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
or with pnpm:
|
|
130
|
+
|
|
131
|
+
```bash
|
|
132
|
+
pnpm add tia-gpc-widget
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
### Option 3: Direct CDN (Legacy - Not Recommended)
|
|
136
|
+
|
|
137
|
+
⚠️ **Note:** This method is still supported but **not recommended** for new installations.
|
|
138
|
+
It requires manual updates every time we release a new version.
|
|
139
|
+
**Use the Auto-Update Loader instead** (see Option 1 above).
|
|
140
|
+
|
|
141
|
+
#### jsDelivr - Fixed Version
|
|
142
|
+
|
|
143
|
+
```html
|
|
144
|
+
<!-- ⚠️ Legacy method: Requires manual version updates -->
|
|
145
|
+
<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.9/dist/tia-gpc-widget.standalone.js"></script>
|
|
146
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.9/dist/tia-gpc-widget.standalone.css">
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
#### unpkg - Fixed Version
|
|
150
|
+
|
|
151
|
+
```html
|
|
152
|
+
<!-- ⚠️ Legacy method: Requires manual version updates -->
|
|
153
|
+
<script src="https://unpkg.com/tia-gpc-widget@1.0.9/dist/tia-gpc-widget.standalone.js"></script>
|
|
154
|
+
<link rel="stylesheet" href="https://unpkg.com/tia-gpc-widget@1.0.9/dist/tia-gpc-widget.standalone.css">
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
**Why use the loader instead?**
|
|
158
|
+
- ✅ Automatic updates - no code changes needed
|
|
159
|
+
- ✅ Always get bug fixes and improvements
|
|
160
|
+
- ✅ Smaller initial load (~2KB vs ~420KB until needed)
|
|
161
|
+
- ✅ Built-in error handling and fallbacks
|
|
162
|
+
|
|
163
|
+
**For existing installations:** See [Migration Guide](MIGRATION.md) to upgrade to the auto-update loader.
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
## ⚡ Quick Start
|
|
168
|
+
|
|
169
|
+
### In Plain HTML
|
|
170
|
+
|
|
171
|
+
```html
|
|
172
|
+
<!DOCTYPE html>
|
|
173
|
+
<html lang="en">
|
|
174
|
+
<head>
|
|
175
|
+
<meta charset="UTF-8">
|
|
176
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
177
|
+
<title>My App with TIA GPC</title>
|
|
178
|
+
</head>
|
|
179
|
+
<body>
|
|
180
|
+
<h1>My Application</h1>
|
|
181
|
+
|
|
182
|
+
<!-- TIA GPC Widget -->
|
|
183
|
+
<tia-gpc-widget
|
|
184
|
+
token="your-license-token-here"
|
|
185
|
+
theme="auto"
|
|
186
|
+
position="bottom-right"
|
|
187
|
+
language="en"
|
|
188
|
+
></tia-gpc-widget>
|
|
189
|
+
|
|
190
|
+
<!-- Auto-Update Loader (loads latest version automatically) -->
|
|
191
|
+
<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@latest/dist/loader.min.js"></script>
|
|
192
|
+
</body>
|
|
193
|
+
</html>
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
### In React
|
|
197
|
+
|
|
198
|
+
```jsx
|
|
199
|
+
import { TiaGPCWidget } from 'tia-gpc-widget';
|
|
200
|
+
import 'tia-gpc-widget/styles';
|
|
201
|
+
|
|
202
|
+
function App() {
|
|
203
|
+
return (
|
|
204
|
+
<div>
|
|
205
|
+
<h1>My Application</h1>
|
|
206
|
+
<TiaGPCWidget
|
|
207
|
+
token="your-license-token-here"
|
|
208
|
+
theme="auto"
|
|
209
|
+
position="bottom-right"
|
|
210
|
+
language="en"
|
|
211
|
+
/>
|
|
212
|
+
</div>
|
|
213
|
+
);
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
export default App;
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
---
|
|
220
|
+
|
|
221
|
+
## 📚 Framework Examples
|
|
222
|
+
|
|
223
|
+
> **💡 Important:** The examples below may show both installation methods:
|
|
224
|
+
> - **Recommended:** Auto-Update Loader (install once, updates automatically)
|
|
225
|
+
> - **Legacy:** Direct CDN with fixed version (requires manual updates)
|
|
226
|
+
>
|
|
227
|
+
> **For new installations, always use the Auto-Update Loader** shown in [Option 1](#option-1-auto-update-loader-recommended).
|
|
228
|
+
|
|
229
|
+
### 1. React
|
|
230
|
+
|
|
231
|
+
#### Installation
|
|
232
|
+
|
|
233
|
+
```bash
|
|
234
|
+
npm install tia-gpc-widget
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
#### Basic Usage
|
|
238
|
+
|
|
239
|
+
```jsx
|
|
240
|
+
import { TiaGPCWidget } from 'tia-gpc-widget';
|
|
241
|
+
import 'tia-gpc-widget/styles';
|
|
242
|
+
|
|
243
|
+
function App() {
|
|
244
|
+
return (
|
|
245
|
+
<TiaGPCWidget
|
|
246
|
+
token="your-license-token"
|
|
247
|
+
theme="auto"
|
|
248
|
+
position="bottom-right"
|
|
249
|
+
language="en"
|
|
250
|
+
primaryColor="#2563eb"
|
|
251
|
+
onReady={() => console.log('Widget ready')}
|
|
252
|
+
onError={(error) => console.error('Error:', error)}
|
|
253
|
+
/>
|
|
254
|
+
);
|
|
255
|
+
}
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
#### Advanced Configuration
|
|
259
|
+
|
|
260
|
+
```jsx
|
|
261
|
+
import { TiaGPCWidget, WIDGET_POSITIONS, THEMES, LANGUAGES } from 'tia-gpc-widget';
|
|
262
|
+
import 'tia-gpc-widget/styles';
|
|
263
|
+
|
|
264
|
+
function App() {
|
|
265
|
+
const handleReady = () => {
|
|
266
|
+
console.log('✅ Widget initialized successfully');
|
|
267
|
+
};
|
|
268
|
+
|
|
269
|
+
const handleError = (error) => {
|
|
270
|
+
console.error('❌ Widget error:', error);
|
|
271
|
+
};
|
|
272
|
+
|
|
273
|
+
return (
|
|
274
|
+
<TiaGPCWidget
|
|
275
|
+
token="your-license-token"
|
|
276
|
+
theme={THEMES.AUTO}
|
|
277
|
+
position={WIDGET_POSITIONS.BOTTOM_RIGHT}
|
|
278
|
+
language={LANGUAGES.EN}
|
|
279
|
+
primaryColor="#10b981"
|
|
280
|
+
width="450px"
|
|
281
|
+
height="650px"
|
|
282
|
+
autoOpen={false}
|
|
283
|
+
showBranding={true}
|
|
284
|
+
mobileFullscreen={true}
|
|
285
|
+
onReady={handleReady}
|
|
286
|
+
onError={handleError}
|
|
287
|
+
onClose={() => console.log('Widget closed')}
|
|
288
|
+
/>
|
|
289
|
+
);
|
|
290
|
+
}
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
---
|
|
294
|
+
|
|
295
|
+
### 2. HTML / Vanilla JavaScript
|
|
296
|
+
|
|
297
|
+
#### Method 1: Using HTML element directly
|
|
298
|
+
|
|
299
|
+
```html
|
|
300
|
+
<!DOCTYPE html>
|
|
301
|
+
<html lang="en">
|
|
302
|
+
<head>
|
|
303
|
+
<meta charset="UTF-8">
|
|
304
|
+
<title>TIA GPC Widget - Plain HTML</title>
|
|
305
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.css">
|
|
306
|
+
</head>
|
|
307
|
+
<body>
|
|
308
|
+
<h1>My Website</h1>
|
|
309
|
+
|
|
310
|
+
<!-- Widget as HTML element -->
|
|
311
|
+
<tia-gpc-widget
|
|
312
|
+
token="your-license-token"
|
|
313
|
+
theme="light"
|
|
314
|
+
position="bottom-right"
|
|
315
|
+
language="en"
|
|
316
|
+
primary-color="#3b82f6"
|
|
317
|
+
width="400px"
|
|
318
|
+
height="600px"
|
|
319
|
+
auto-open="false"
|
|
320
|
+
show-branding="true"
|
|
321
|
+
></tia-gpc-widget>
|
|
322
|
+
|
|
323
|
+
<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.js"></script>
|
|
324
|
+
|
|
325
|
+
<!-- Optional events -->
|
|
326
|
+
<script>
|
|
327
|
+
const widget = document.querySelector('tia-gpc-widget');
|
|
328
|
+
|
|
329
|
+
widget.addEventListener('ready', () => {
|
|
330
|
+
console.log('Widget ready');
|
|
331
|
+
});
|
|
332
|
+
|
|
333
|
+
widget.addEventListener('error', (e) => {
|
|
334
|
+
console.error('Error:', e.detail);
|
|
335
|
+
});
|
|
336
|
+
|
|
337
|
+
widget.addEventListener('close', () => {
|
|
338
|
+
console.log('Widget closed');
|
|
339
|
+
});
|
|
340
|
+
</script>
|
|
341
|
+
</body>
|
|
342
|
+
</html>
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
#### Method 2: Programmatic creation with JavaScript
|
|
346
|
+
|
|
347
|
+
```html
|
|
348
|
+
<!DOCTYPE html>
|
|
349
|
+
<html lang="en">
|
|
350
|
+
<head>
|
|
351
|
+
<meta charset="UTF-8">
|
|
352
|
+
<title>TIA GPC Widget - Programmatic</title>
|
|
353
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.css">
|
|
354
|
+
</head>
|
|
355
|
+
<body>
|
|
356
|
+
<h1>My Website</h1>
|
|
357
|
+
<button id="create-widget">Create Widget</button>
|
|
358
|
+
|
|
359
|
+
<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.js"></script>
|
|
360
|
+
<script>
|
|
361
|
+
document.getElementById('create-widget').addEventListener('click', () => {
|
|
362
|
+
// Use the global TiaGPC API
|
|
363
|
+
const widget = TiaGPC.create({
|
|
364
|
+
token: 'your-license-token',
|
|
365
|
+
theme: 'auto',
|
|
366
|
+
position: TiaGPC.POSITIONS.BOTTOM_RIGHT,
|
|
367
|
+
language: TiaGPC.LANGUAGES.EN,
|
|
368
|
+
primaryColor: '#3b82f6',
|
|
369
|
+
autoOpen: false,
|
|
370
|
+
onReady: () => console.log('✅ Widget ready'),
|
|
371
|
+
onError: (error) => console.error('❌ Error:', error),
|
|
372
|
+
onClose: () => console.log('Widget closed')
|
|
373
|
+
});
|
|
374
|
+
|
|
375
|
+
console.log('Widget created:', widget);
|
|
376
|
+
});
|
|
377
|
+
|
|
378
|
+
// View widget information
|
|
379
|
+
TiaGPC.info();
|
|
380
|
+
</script>
|
|
381
|
+
</body>
|
|
382
|
+
</html>
|
|
383
|
+
```
|
|
384
|
+
|
|
385
|
+
---
|
|
386
|
+
|
|
387
|
+
### 3. Angular
|
|
388
|
+
|
|
389
|
+
#### Step 1: Install the widget
|
|
390
|
+
|
|
391
|
+
```bash
|
|
392
|
+
npm install tia-gpc-widget
|
|
393
|
+
```
|
|
394
|
+
|
|
395
|
+
#### Step 2: Configure Angular for Web Components
|
|
396
|
+
|
|
397
|
+
In `src/main.ts` or `src/polyfills.ts`, add:
|
|
398
|
+
|
|
399
|
+
```typescript
|
|
400
|
+
// Enable Custom Elements (Web Components)
|
|
401
|
+
import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
|
|
402
|
+
```
|
|
403
|
+
|
|
404
|
+
In your main module (`app.module.ts`):
|
|
405
|
+
|
|
406
|
+
```typescript
|
|
407
|
+
import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
|
|
408
|
+
import { BrowserModule } from '@angular/platform-browser';
|
|
409
|
+
import { AppComponent } from './app.component';
|
|
410
|
+
|
|
411
|
+
@NgModule({
|
|
412
|
+
declarations: [AppComponent],
|
|
413
|
+
imports: [BrowserModule],
|
|
414
|
+
schemas: [CUSTOM_ELEMENTS_SCHEMA], // ← Important
|
|
415
|
+
bootstrap: [AppComponent]
|
|
416
|
+
})
|
|
417
|
+
export class AppModule { }
|
|
418
|
+
```
|
|
419
|
+
|
|
420
|
+
#### Step 3: Import widget files
|
|
421
|
+
|
|
422
|
+
In `angular.json`, add the CSS and JS files:
|
|
423
|
+
|
|
424
|
+
```json
|
|
425
|
+
{
|
|
426
|
+
"projects": {
|
|
427
|
+
"your-project": {
|
|
428
|
+
"architect": {
|
|
429
|
+
"build": {
|
|
430
|
+
"options": {
|
|
431
|
+
"styles": [
|
|
432
|
+
"src/styles.css",
|
|
433
|
+
"node_modules/tia-gpc-widget/dist/tia-gpc-widget.standalone.css"
|
|
434
|
+
],
|
|
435
|
+
"scripts": [
|
|
436
|
+
"node_modules/tia-gpc-widget/dist/tia-gpc-widget.standalone.js"
|
|
437
|
+
]
|
|
438
|
+
}
|
|
439
|
+
}
|
|
440
|
+
}
|
|
441
|
+
}
|
|
442
|
+
}
|
|
443
|
+
}
|
|
444
|
+
```
|
|
445
|
+
|
|
446
|
+
#### Step 4: Use the widget in your component
|
|
447
|
+
|
|
448
|
+
```typescript
|
|
449
|
+
// app.component.ts
|
|
450
|
+
import { Component, OnInit } from '@angular/core';
|
|
451
|
+
|
|
452
|
+
declare global {
|
|
453
|
+
interface Window {
|
|
454
|
+
TiaGPC: any;
|
|
455
|
+
}
|
|
456
|
+
}
|
|
457
|
+
|
|
458
|
+
@Component({
|
|
459
|
+
selector: 'app-root',
|
|
460
|
+
template: `
|
|
461
|
+
<h1>My Angular Application</h1>
|
|
462
|
+
|
|
463
|
+
<!-- Option 1: Direct HTML element -->
|
|
464
|
+
<tia-gpc-widget
|
|
465
|
+
[attr.token]="widgetToken"
|
|
466
|
+
[attr.theme]="theme"
|
|
467
|
+
[attr.position]="position"
|
|
468
|
+
[attr.language]="language"
|
|
469
|
+
(ready)="onWidgetReady()"
|
|
470
|
+
(error)="onWidgetError($event)"
|
|
471
|
+
></tia-gpc-widget>
|
|
472
|
+
`
|
|
473
|
+
})
|
|
474
|
+
export class AppComponent implements OnInit {
|
|
475
|
+
widgetToken = 'your-license-token';
|
|
476
|
+
theme = 'auto';
|
|
477
|
+
position = 'bottom-right';
|
|
478
|
+
language = 'en';
|
|
479
|
+
|
|
480
|
+
ngOnInit() {
|
|
481
|
+
console.log('TiaGPC available:', window.TiaGPC);
|
|
482
|
+
}
|
|
483
|
+
|
|
484
|
+
onWidgetReady() {
|
|
485
|
+
console.log('✅ TIA GPC widget ready');
|
|
486
|
+
}
|
|
487
|
+
|
|
488
|
+
onWidgetError(event: any) {
|
|
489
|
+
console.error('❌ Widget error:', event.detail);
|
|
490
|
+
}
|
|
491
|
+
}
|
|
492
|
+
```
|
|
493
|
+
|
|
494
|
+
#### Alternative option: Programmatic creation
|
|
495
|
+
|
|
496
|
+
```typescript
|
|
497
|
+
// app.component.ts
|
|
498
|
+
import { Component, OnInit } from '@angular/core';
|
|
499
|
+
|
|
500
|
+
@Component({
|
|
501
|
+
selector: 'app-root',
|
|
502
|
+
template: `
|
|
503
|
+
<h1>My Angular Application</h1>
|
|
504
|
+
<button (click)="createWidget()">Create Widget</button>
|
|
505
|
+
<div #widgetContainer></div>
|
|
506
|
+
`
|
|
507
|
+
})
|
|
508
|
+
export class AppComponent implements OnInit {
|
|
509
|
+
ngOnInit() {
|
|
510
|
+
this.createWidget();
|
|
511
|
+
}
|
|
512
|
+
|
|
513
|
+
createWidget() {
|
|
514
|
+
if (window.TiaGPC) {
|
|
515
|
+
window.TiaGPC.create({
|
|
516
|
+
token: 'your-license-token',
|
|
517
|
+
theme: 'auto',
|
|
518
|
+
language: 'en',
|
|
519
|
+
onReady: () => console.log('Widget ready'),
|
|
520
|
+
onError: (err: any) => console.error(err)
|
|
521
|
+
});
|
|
522
|
+
}
|
|
523
|
+
}
|
|
524
|
+
}
|
|
525
|
+
```
|
|
526
|
+
|
|
527
|
+
---
|
|
528
|
+
|
|
529
|
+
### 4. ASP.NET / ASPX
|
|
530
|
+
|
|
531
|
+
#### Option 1: In an ASPX page
|
|
532
|
+
|
|
533
|
+
```aspx
|
|
534
|
+
<%@ Page Language="C#" AutoEventWireup="true" %>
|
|
535
|
+
|
|
536
|
+
<!DOCTYPE html>
|
|
537
|
+
<html>
|
|
538
|
+
<head>
|
|
539
|
+
<title>TIA GPC Widget - ASP.NET</title>
|
|
540
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.css" />
|
|
541
|
+
</head>
|
|
542
|
+
<body>
|
|
543
|
+
<form id="form1" runat="server">
|
|
544
|
+
<h1>My ASP.NET Application</h1>
|
|
545
|
+
|
|
546
|
+
<!-- TIA GPC Widget -->
|
|
547
|
+
<tia-gpc-widget
|
|
548
|
+
token="<%= ConfigurationManager.AppSettings["TiaGpcToken"] %>"
|
|
549
|
+
theme="auto"
|
|
550
|
+
position="bottom-right"
|
|
551
|
+
language="en"
|
|
552
|
+
primary-color="#2563eb"
|
|
553
|
+
></tia-gpc-widget>
|
|
554
|
+
</form>
|
|
555
|
+
|
|
556
|
+
<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.js"></script>
|
|
557
|
+
<script>
|
|
558
|
+
// Optional events
|
|
559
|
+
document.querySelector('tia-gpc-widget').addEventListener('ready', function() {
|
|
560
|
+
console.log('TIA GPC Widget initialized');
|
|
561
|
+
});
|
|
562
|
+
</script>
|
|
563
|
+
</body>
|
|
564
|
+
</html>
|
|
565
|
+
```
|
|
566
|
+
|
|
567
|
+
#### Option 2: With Master Page
|
|
568
|
+
|
|
569
|
+
In your `Site.Master`:
|
|
570
|
+
|
|
571
|
+
```aspx
|
|
572
|
+
<head runat="server">
|
|
573
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.css" />
|
|
574
|
+
</head>
|
|
575
|
+
<body>
|
|
576
|
+
<asp:ContentPlaceHolder ID="MainContent" runat="server">
|
|
577
|
+
</asp:ContentPlaceHolder>
|
|
578
|
+
|
|
579
|
+
<!-- Global widget -->
|
|
580
|
+
<tia-gpc-widget
|
|
581
|
+
token="<%= GetTiaGpcToken() %>"
|
|
582
|
+
theme="auto"
|
|
583
|
+
language="en"
|
|
584
|
+
></tia-gpc-widget>
|
|
585
|
+
|
|
586
|
+
<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.js"></script>
|
|
587
|
+
</body>
|
|
588
|
+
```
|
|
589
|
+
|
|
590
|
+
In your `Site.Master.cs`:
|
|
591
|
+
|
|
592
|
+
```csharp
|
|
593
|
+
public partial class SiteMaster : MasterPage
|
|
594
|
+
{
|
|
595
|
+
protected string GetTiaGpcToken()
|
|
596
|
+
{
|
|
597
|
+
return ConfigurationManager.AppSettings["TiaGpcToken"];
|
|
598
|
+
}
|
|
599
|
+
}
|
|
600
|
+
```
|
|
601
|
+
|
|
602
|
+
#### Option 3: MVC / Razor
|
|
603
|
+
|
|
604
|
+
In your layout `_Layout.cshtml`:
|
|
605
|
+
|
|
606
|
+
```html
|
|
607
|
+
<!DOCTYPE html>
|
|
608
|
+
<html>
|
|
609
|
+
<head>
|
|
610
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.css" />
|
|
611
|
+
</head>
|
|
612
|
+
<body>
|
|
613
|
+
@RenderBody()
|
|
614
|
+
|
|
615
|
+
<!-- TIA GPC Widget -->
|
|
616
|
+
<tia-gpc-widget
|
|
617
|
+
token="@ViewBag.TiaGpcToken"
|
|
618
|
+
theme="auto"
|
|
619
|
+
language="en"
|
|
620
|
+
></tia-gpc-widget>
|
|
621
|
+
|
|
622
|
+
<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.js"></script>
|
|
623
|
+
</body>
|
|
624
|
+
</html>
|
|
625
|
+
```
|
|
626
|
+
|
|
627
|
+
In your `Controller`:
|
|
628
|
+
|
|
629
|
+
```csharp
|
|
630
|
+
public class HomeController : Controller
|
|
631
|
+
{
|
|
632
|
+
public ActionResult Index()
|
|
633
|
+
{
|
|
634
|
+
ViewBag.TiaGpcToken = ConfigurationManager.AppSettings["TiaGpcToken"];
|
|
635
|
+
return View();
|
|
636
|
+
}
|
|
637
|
+
}
|
|
638
|
+
```
|
|
639
|
+
|
|
640
|
+
---
|
|
641
|
+
|
|
642
|
+
### 5. Vue.js
|
|
643
|
+
|
|
644
|
+
#### Installation
|
|
645
|
+
|
|
646
|
+
```bash
|
|
647
|
+
npm install tia-gpc-widget
|
|
648
|
+
```
|
|
649
|
+
|
|
650
|
+
#### Configuration
|
|
651
|
+
|
|
652
|
+
In `main.js` or `main.ts`:
|
|
653
|
+
|
|
654
|
+
```javascript
|
|
655
|
+
import { createApp } from 'vue';
|
|
656
|
+
import App from './App.vue';
|
|
657
|
+
|
|
658
|
+
// Import the standalone widget
|
|
659
|
+
import 'tia-gpc-widget/dist/tia-gpc-widget.standalone.js';
|
|
660
|
+
import 'tia-gpc-widget/dist/tia-gpc-widget.standalone.css';
|
|
661
|
+
|
|
662
|
+
const app = createApp(App);
|
|
663
|
+
|
|
664
|
+
// Configure Vue to ignore custom elements
|
|
665
|
+
app.config.compilerOptions.isCustomElement = (tag) => tag === 'tia-gpc-widget';
|
|
666
|
+
|
|
667
|
+
app.mount('#app');
|
|
668
|
+
```
|
|
669
|
+
|
|
670
|
+
#### Usage in components
|
|
671
|
+
|
|
672
|
+
```vue
|
|
673
|
+
<template>
|
|
674
|
+
<div>
|
|
675
|
+
<h1>My Vue Application</h1>
|
|
676
|
+
|
|
677
|
+
<!-- TIA GPC Widget -->
|
|
678
|
+
<tia-gpc-widget
|
|
679
|
+
:token="widgetToken"
|
|
680
|
+
:theme="theme"
|
|
681
|
+
:language="language"
|
|
682
|
+
position="bottom-right"
|
|
683
|
+
@ready="onReady"
|
|
684
|
+
@error="onError"
|
|
685
|
+
></tia-gpc-widget>
|
|
686
|
+
</div>
|
|
687
|
+
</template>
|
|
688
|
+
|
|
689
|
+
<script setup>
|
|
690
|
+
import { ref, onMounted } from 'vue';
|
|
691
|
+
|
|
692
|
+
const widgetToken = ref('your-license-token');
|
|
693
|
+
const theme = ref('auto');
|
|
694
|
+
const language = ref('en');
|
|
695
|
+
|
|
696
|
+
const onReady = () => {
|
|
697
|
+
console.log('✅ TIA GPC Widget ready');
|
|
698
|
+
};
|
|
699
|
+
|
|
700
|
+
const onError = (event) => {
|
|
701
|
+
console.error('❌ Error:', event.detail);
|
|
702
|
+
};
|
|
703
|
+
|
|
704
|
+
onMounted(() => {
|
|
705
|
+
console.log('TiaGPC available:', window.TiaGPC);
|
|
706
|
+
});
|
|
707
|
+
</script>
|
|
708
|
+
```
|
|
709
|
+
|
|
710
|
+
---
|
|
711
|
+
|
|
712
|
+
### 6. Next.js
|
|
713
|
+
|
|
714
|
+
#### Installation
|
|
715
|
+
|
|
716
|
+
```bash
|
|
717
|
+
npm install tia-gpc-widget
|
|
718
|
+
```
|
|
719
|
+
|
|
720
|
+
#### Usage (with Client Component)
|
|
721
|
+
|
|
722
|
+
```jsx
|
|
723
|
+
// components/TiaWidget.jsx
|
|
724
|
+
'use client'; // ← Important: Client Component
|
|
725
|
+
|
|
726
|
+
import { useEffect } from 'react';
|
|
727
|
+
|
|
728
|
+
export default function TiaWidget() {
|
|
729
|
+
useEffect(() => {
|
|
730
|
+
// Import widget only on client side
|
|
731
|
+
import('tia-gpc-widget/dist/tia-gpc-widget.standalone.js');
|
|
732
|
+
}, []);
|
|
733
|
+
|
|
734
|
+
return (
|
|
735
|
+
<>
|
|
736
|
+
{/* CSS */}
|
|
737
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.css" />
|
|
738
|
+
|
|
739
|
+
{/* Widget */}
|
|
740
|
+
<tia-gpc-widget
|
|
741
|
+
token={process.env.NEXT_PUBLIC_TIA_GPC_TOKEN}
|
|
742
|
+
theme="auto"
|
|
743
|
+
language="en"
|
|
744
|
+
></tia-gpc-widget>
|
|
745
|
+
</>
|
|
746
|
+
);
|
|
747
|
+
}
|
|
748
|
+
```
|
|
749
|
+
|
|
750
|
+
In your page:
|
|
751
|
+
|
|
752
|
+
```jsx
|
|
753
|
+
// app/page.jsx
|
|
754
|
+
import TiaWidget from '@/components/TiaWidget';
|
|
755
|
+
|
|
756
|
+
export default function Home() {
|
|
757
|
+
return (
|
|
758
|
+
<main>
|
|
759
|
+
<h1>My Next.js App</h1>
|
|
760
|
+
<TiaWidget />
|
|
761
|
+
</main>
|
|
762
|
+
);
|
|
763
|
+
}
|
|
764
|
+
```
|
|
765
|
+
|
|
766
|
+
---
|
|
767
|
+
|
|
768
|
+
### 7. PHP
|
|
769
|
+
|
|
770
|
+
```php
|
|
771
|
+
<!DOCTYPE html>
|
|
772
|
+
<html lang="en">
|
|
773
|
+
<head>
|
|
774
|
+
<meta charset="UTF-8">
|
|
775
|
+
<title>TIA GPC Widget - PHP</title>
|
|
776
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.css">
|
|
777
|
+
</head>
|
|
778
|
+
<body>
|
|
779
|
+
<h1>My PHP Application</h1>
|
|
780
|
+
|
|
781
|
+
<?php
|
|
782
|
+
// Get token from environment variables or config
|
|
783
|
+
$tiaGpcToken = getenv('TIA_GPC_TOKEN') ?: 'your-license-token';
|
|
784
|
+
$userLanguage = $_SESSION['user_language'] ?? 'en';
|
|
785
|
+
?>
|
|
786
|
+
|
|
787
|
+
<!-- TIA GPC Widget -->
|
|
788
|
+
<tia-gpc-widget
|
|
789
|
+
token="<?php echo htmlspecialchars($tiaGpcToken); ?>"
|
|
790
|
+
theme="auto"
|
|
791
|
+
position="bottom-right"
|
|
792
|
+
language="<?php echo htmlspecialchars($userLanguage); ?>"
|
|
793
|
+
></tia-gpc-widget>
|
|
794
|
+
|
|
795
|
+
<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.js"></script>
|
|
796
|
+
</body>
|
|
797
|
+
</html>
|
|
798
|
+
```
|
|
799
|
+
|
|
800
|
+
---
|
|
801
|
+
|
|
802
|
+
## 🎛️ API & Configuration
|
|
803
|
+
|
|
804
|
+
### Props/Attributes
|
|
805
|
+
|
|
806
|
+
All frameworks support the same attributes:
|
|
807
|
+
|
|
808
|
+
| Attribute | Type | Default | Description |
|
|
809
|
+
|----------|------|-------------|-------------|
|
|
810
|
+
| `token` | `string` | **Required** | TIA GPC license token |
|
|
811
|
+
| `theme` | `'auto' \| 'light' \| 'dark'` | `'auto'` | Widget theme |
|
|
812
|
+
| `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | Screen position |
|
|
813
|
+
| `language` | `'es' \| 'en' \| 'fr'` | `'es'` | Widget language |
|
|
814
|
+
| `primary-color` | `string` | `'#2563eb'` | Primary color (hexadecimal) |
|
|
815
|
+
| `width` | `string` | `'400px'` | Widget width |
|
|
816
|
+
| `height` | `string` | `'600px'` | Widget height |
|
|
817
|
+
| `api-url` | `string` | Default API | Custom API URL |
|
|
818
|
+
| `turnstile-site-key` | `string` | - | Cloudflare Turnstile site key |
|
|
819
|
+
| `auto-open` | `boolean` | `false` | Auto-open on load |
|
|
820
|
+
| `show-branding` | `boolean` | `true` | Show TIA GPC branding |
|
|
821
|
+
| `mobile-fullscreen` | `boolean` | `true` | Fullscreen on mobile |
|
|
822
|
+
|
|
823
|
+
### Events
|
|
824
|
+
|
|
825
|
+
| Event | Description | Payload |
|
|
826
|
+
|--------|-------------|---------|
|
|
827
|
+
| `ready` | Fired when widget is ready | - |
|
|
828
|
+
| `error` | Fired when an error occurs | `{ detail: ErrorObject }` |
|
|
829
|
+
| `close` | Fired when widget closes | - |
|
|
830
|
+
|
|
831
|
+
#### Event usage example
|
|
832
|
+
|
|
833
|
+
```html
|
|
834
|
+
<script>
|
|
835
|
+
const widget = document.querySelector('tia-gpc-widget');
|
|
836
|
+
|
|
837
|
+
widget.addEventListener('ready', () => {
|
|
838
|
+
console.log('Widget ready');
|
|
839
|
+
});
|
|
840
|
+
|
|
841
|
+
widget.addEventListener('error', (e) => {
|
|
842
|
+
console.error('Error:', e.detail);
|
|
843
|
+
// Send to logging system
|
|
844
|
+
});
|
|
845
|
+
|
|
846
|
+
widget.addEventListener('close', () => {
|
|
847
|
+
console.log('User closed the widget');
|
|
848
|
+
// Analytics or tracking
|
|
849
|
+
});
|
|
850
|
+
</script>
|
|
851
|
+
```
|
|
852
|
+
|
|
853
|
+
### Programmatic API (JavaScript)
|
|
854
|
+
|
|
855
|
+
The widget exposes a global `TiaGPC` API for programmatic control:
|
|
856
|
+
|
|
857
|
+
```javascript
|
|
858
|
+
// Create widget programmatically
|
|
859
|
+
const widget = TiaGPC.create({
|
|
860
|
+
token: 'your-token',
|
|
861
|
+
theme: 'dark',
|
|
862
|
+
language: 'en',
|
|
863
|
+
position: TiaGPC.POSITIONS.BOTTOM_LEFT,
|
|
864
|
+
onReady: () => console.log('Ready'),
|
|
865
|
+
onError: (err) => console.error(err)
|
|
866
|
+
});
|
|
867
|
+
|
|
868
|
+
// Open widget
|
|
869
|
+
widget.open();
|
|
870
|
+
|
|
871
|
+
// Close widget
|
|
872
|
+
widget.close();
|
|
873
|
+
|
|
874
|
+
// View information
|
|
875
|
+
TiaGPC.info();
|
|
876
|
+
|
|
877
|
+
// Available constants
|
|
878
|
+
console.log(TiaGPC.POSITIONS); // { BOTTOM_RIGHT, BOTTOM_LEFT, ... }
|
|
879
|
+
console.log(TiaGPC.THEMES); // { AUTO, LIGHT, DARK }
|
|
880
|
+
console.log(TiaGPC.LANGUAGES); // { ES, EN, FR }
|
|
881
|
+
```
|
|
882
|
+
|
|
883
|
+
---
|
|
884
|
+
|
|
885
|
+
## 🎨 Customization
|
|
886
|
+
|
|
887
|
+
### Themes
|
|
888
|
+
|
|
889
|
+
```html
|
|
890
|
+
<!-- Automatic (follows system preferences) -->
|
|
891
|
+
<tia-gpc-widget theme="auto"></tia-gpc-widget>
|
|
892
|
+
|
|
893
|
+
<!-- Light -->
|
|
894
|
+
<tia-gpc-widget theme="light"></tia-gpc-widget>
|
|
895
|
+
|
|
896
|
+
<!-- Dark -->
|
|
897
|
+
<tia-gpc-widget theme="dark"></tia-gpc-widget>
|
|
898
|
+
```
|
|
899
|
+
|
|
900
|
+
### Positions
|
|
901
|
+
|
|
902
|
+
```html
|
|
903
|
+
<!-- Bottom right corner (default) -->
|
|
904
|
+
<tia-gpc-widget position="bottom-right"></tia-gpc-widget>
|
|
905
|
+
|
|
906
|
+
<!-- Bottom left corner -->
|
|
907
|
+
<tia-gpc-widget position="bottom-left"></tia-gpc-widget>
|
|
908
|
+
|
|
909
|
+
<!-- Top right corner -->
|
|
910
|
+
<tia-gpc-widget position="top-right"></tia-gpc-widget>
|
|
911
|
+
|
|
912
|
+
<!-- Top left corner -->
|
|
913
|
+
<tia-gpc-widget position="top-left"></tia-gpc-widget>
|
|
914
|
+
```
|
|
915
|
+
|
|
916
|
+
### Languages
|
|
917
|
+
|
|
918
|
+
```html
|
|
919
|
+
<!-- Spanish -->
|
|
920
|
+
<tia-gpc-widget language="es"></tia-gpc-widget>
|
|
921
|
+
|
|
922
|
+
<!-- English -->
|
|
923
|
+
<tia-gpc-widget language="en"></tia-gpc-widget>
|
|
924
|
+
|
|
925
|
+
<!-- French -->
|
|
926
|
+
<tia-gpc-widget language="fr"></tia-gpc-widget>
|
|
927
|
+
```
|
|
928
|
+
|
|
929
|
+
### Colors
|
|
930
|
+
|
|
931
|
+
```html
|
|
932
|
+
<!-- Custom color -->
|
|
933
|
+
<tia-gpc-widget
|
|
934
|
+
primary-color="#10b981"
|
|
935
|
+
></tia-gpc-widget>
|
|
936
|
+
|
|
937
|
+
<!-- Blue (default) -->
|
|
938
|
+
<tia-gpc-widget primary-color="#2563eb"></tia-gpc-widget>
|
|
939
|
+
|
|
940
|
+
<!-- Green -->
|
|
941
|
+
<tia-gpc-widget primary-color="#16a34a"></tia-gpc-widget>
|
|
942
|
+
|
|
943
|
+
<!-- Purple -->
|
|
944
|
+
<tia-gpc-widget primary-color="#9333ea"></tia-gpc-widget>
|
|
945
|
+
```
|
|
946
|
+
|
|
947
|
+
---
|
|
948
|
+
|
|
949
|
+
## 🛠️ Build & Development
|
|
950
|
+
|
|
951
|
+
### Available scripts
|
|
952
|
+
|
|
953
|
+
```bash
|
|
954
|
+
# Development (dev mode with hot reload)
|
|
955
|
+
npm run dev
|
|
956
|
+
|
|
957
|
+
# Complete build (NPM + Standalone)
|
|
958
|
+
npm run build
|
|
959
|
+
|
|
960
|
+
# Build only for NPM (without bundled React)
|
|
961
|
+
npm run build:npm
|
|
962
|
+
|
|
963
|
+
# Standalone build (with bundled React)
|
|
964
|
+
npm run build:standalone
|
|
965
|
+
|
|
966
|
+
# Lint
|
|
967
|
+
npm run lint
|
|
968
|
+
|
|
969
|
+
# Preview
|
|
970
|
+
npm run preview
|
|
971
|
+
```
|
|
972
|
+
|
|
973
|
+
### Generated file structure
|
|
974
|
+
|
|
975
|
+
```
|
|
976
|
+
dist/
|
|
977
|
+
├── tia-gpc.es.js # ESM build for NPM
|
|
978
|
+
├── tia-gpc.cjs.js # CommonJS build for NPM
|
|
979
|
+
├── tia-gpc.css # CSS for NPM build
|
|
980
|
+
├── tia-gpc-widget.standalone.js # Standalone build (IIFE with React)
|
|
981
|
+
└── tia-gpc-widget.standalone.css # CSS for standalone
|
|
982
|
+
```
|
|
983
|
+
|
|
984
|
+
### Which file to use?
|
|
985
|
+
|
|
986
|
+
| Environment | File to use |
|
|
987
|
+
|---------|----------------|
|
|
988
|
+
| React, Vue (with build system) | `tia-gpc.es.js` + `tia-gpc.css` |
|
|
989
|
+
| Node.js CommonJS | `tia-gpc.cjs.js` + `tia-gpc.css` |
|
|
990
|
+
| Plain HTML, Angular, ASP.NET, PHP | `tia-gpc-widget.standalone.js` + `tia-gpc-widget.standalone.css` |
|
|
991
|
+
|
|
992
|
+
---
|
|
993
|
+
|
|
994
|
+
## 📤 Publishing
|
|
995
|
+
|
|
996
|
+
### Publish to NPM (Public)
|
|
997
|
+
|
|
998
|
+
```bash
|
|
999
|
+
# 1. Login to NPM
|
|
1000
|
+
npm login
|
|
1001
|
+
|
|
1002
|
+
# 2. Build the project
|
|
1003
|
+
npm run build
|
|
1004
|
+
|
|
1005
|
+
# 3. Publish
|
|
1006
|
+
npm publish
|
|
1007
|
+
```
|
|
1008
|
+
|
|
1009
|
+
### Publish to Private NPM / GitLab Package Registry
|
|
1010
|
+
|
|
1011
|
+
#### Configure `.npmrc`
|
|
1012
|
+
|
|
1013
|
+
Create an `.npmrc` file in the project root:
|
|
1014
|
+
|
|
1015
|
+
```ini
|
|
1016
|
+
# For GitLab Package Registry
|
|
1017
|
+
@your-scope:registry=https://gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/
|
|
1018
|
+
//gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/:_authToken=${CI_JOB_TOKEN}
|
|
1019
|
+
```
|
|
1020
|
+
|
|
1021
|
+
#### Update `package.json`
|
|
1022
|
+
|
|
1023
|
+
```json
|
|
1024
|
+
{
|
|
1025
|
+
"name": "@your-scope/tia-gpc-widget",
|
|
1026
|
+
"publishConfig": {
|
|
1027
|
+
"@your-scope:registry": "https://gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/"
|
|
1028
|
+
}
|
|
1029
|
+
}
|
|
1030
|
+
```
|
|
1031
|
+
|
|
1032
|
+
#### Publish
|
|
1033
|
+
|
|
1034
|
+
```bash
|
|
1035
|
+
npm run build
|
|
1036
|
+
npm publish
|
|
1037
|
+
```
|
|
1038
|
+
|
|
1039
|
+
### CDN Distribution
|
|
1040
|
+
|
|
1041
|
+
After publishing to npm, your package is automatically available on these CDNs:
|
|
1042
|
+
|
|
1043
|
+
#### jsDelivr
|
|
1044
|
+
```html
|
|
1045
|
+
<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.js"></script>
|
|
1046
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.css">
|
|
1047
|
+
```
|
|
1048
|
+
|
|
1049
|
+
#### unpkg
|
|
1050
|
+
```html
|
|
1051
|
+
<script src="https://unpkg.com/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.js"></script>
|
|
1052
|
+
<link rel="stylesheet" href="https://unpkg.com/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.css">
|
|
1053
|
+
```
|
|
1054
|
+
|
|
1055
|
+
**Note:** CDNs may take 5-10 minutes to sync after publishing to npm.
|
|
1056
|
+
|
|
1057
|
+
### Manual Distribution
|
|
1058
|
+
|
|
1059
|
+
Copy files from `dist/` to your web server:
|
|
1060
|
+
|
|
1061
|
+
```bash
|
|
1062
|
+
# Copy standalone files to server
|
|
1063
|
+
cp dist/tia-gpc-widget.standalone.* /var/www/html/assets/
|
|
1064
|
+
```
|
|
1065
|
+
|
|
1066
|
+
---
|
|
1067
|
+
|
|
1068
|
+
## 🔐 Getting a License Token
|
|
1069
|
+
|
|
1070
|
+
To use this widget you need a TIA GPC license token. Contact the TIA team to get your token:
|
|
1071
|
+
|
|
1072
|
+
- **Email**: support@tia.com
|
|
1073
|
+
- **Web**: https://tia.com/gpc
|
|
1074
|
+
|
|
1075
|
+
---
|
|
1076
|
+
|
|
1077
|
+
## 📊 Bundle Sizes
|
|
1078
|
+
|
|
1079
|
+
| File | Size (gzip) | Description |
|
|
1080
|
+
|---------|---------------|-------------|
|
|
1081
|
+
| `tia-gpc.es.js` | ~45 KB | NPM build (without React) |
|
|
1082
|
+
| `tia-gpc-widget.standalone.js` | ~180 KB | Standalone build (with React) |
|
|
1083
|
+
| `*.css` | ~15 KB | Styles |
|
|
1084
|
+
|
|
1085
|
+
The standalone bundle is larger because it includes React and all dependencies.
|
|
1086
|
+
|
|
1087
|
+
---
|
|
1088
|
+
|
|
1089
|
+
## 🐛 Troubleshooting
|
|
1090
|
+
|
|
1091
|
+
### Widget doesn't appear
|
|
1092
|
+
|
|
1093
|
+
1. Verify you included both files (JS and CSS)
|
|
1094
|
+
2. Check browser console for errors
|
|
1095
|
+
3. Make sure the token is valid
|
|
1096
|
+
|
|
1097
|
+
### Error: "customElements.define() called with incorrect arguments"
|
|
1098
|
+
|
|
1099
|
+
- In Angular: Add `CUSTOM_ELEMENTS_SCHEMA` to your module
|
|
1100
|
+
- In Vue: Configure `isCustomElement` in compiler options
|
|
1101
|
+
|
|
1102
|
+
### CSS Conflicts
|
|
1103
|
+
|
|
1104
|
+
The widget uses `gpc-` prefixes on all classes to avoid conflicts. If there are still issues, you can increase specificity:
|
|
1105
|
+
|
|
1106
|
+
```css
|
|
1107
|
+
.your-container tia-gpc-widget {
|
|
1108
|
+
/* your custom styles */
|
|
1109
|
+
}
|
|
1110
|
+
```
|
|
1111
|
+
|
|
1112
|
+
### React is not defined (in standalone build)
|
|
1113
|
+
|
|
1114
|
+
If you see this error, make sure you're using the `standalone.js` file and not the regular NPM build.
|
|
1115
|
+
|
|
1116
|
+
---
|
|
1117
|
+
|
|
1118
|
+
## 📝 License
|
|
1119
|
+
|
|
1120
|
+
UNLICENSED - Internal use by TIA
|
|
1121
|
+
|
|
1122
|
+
---
|
|
1123
|
+
|
|
1124
|
+
## 👥 Support
|
|
1125
|
+
|
|
1126
|
+
For technical support:
|
|
1127
|
+
|
|
1128
|
+
- **Email**: support@tia.com
|
|
1129
|
+
- **GitLab Issues**: https://gitlab.com/softia/tiagpc-frontend/issues
|
|
1130
|
+
- **Documentation**: This README
|
|
1131
|
+
|
|
1132
|
+
---
|
|
1133
|
+
|
|
1134
|
+
## 🚀 Changelog
|
|
1135
|
+
|
|
1136
|
+
### v1.0.6 (2025-01-11)
|
|
1137
|
+
|
|
1138
|
+
- ✨ Added CDN support via jsDelivr and unpkg
|
|
1139
|
+
- 📝 Updated documentation to English
|
|
1140
|
+
- 🔧 Added `unpkg` and `jsdelivr` fields to package.json
|
|
1141
|
+
|
|
1142
|
+
### v1.0.0 (2025-01-10)
|
|
1143
|
+
|
|
1144
|
+
- ✨ Initial release
|
|
1145
|
+
- ✅ React support
|
|
1146
|
+
- ✅ Standalone build for HTML/Angular/ASP.NET
|
|
1147
|
+
- ✅ Web Component API
|
|
1148
|
+
- ✅ Light/dark themes
|
|
1149
|
+
- ✅ Internationalization (ES/EN/FR)
|
|
1150
|
+
- ✅ Full customization
|
|
1151
|
+
|
|
1152
|
+
---
|
|
1153
|
+
|
|
1154
|
+
## 📚 Loader Advanced Usage
|
|
1155
|
+
|
|
1156
|
+
### What is the Auto-Update Loader?
|
|
1157
|
+
|
|
1158
|
+
The **TIA GPC Widget Loader** is a revolutionary approach to widget distribution that solves the update problem:
|
|
1159
|
+
|
|
1160
|
+
- **Traditional approach**: Clients must manually update the version number in their code every time you release
|
|
1161
|
+
- **Loader approach**: Clients install once, you control which version they receive via `version.json`
|
|
1162
|
+
|
|
1163
|
+
### How it Works
|
|
1164
|
+
|
|
1165
|
+
1. **Client installs the loader** (one time only):
|
|
1166
|
+
```html
|
|
1167
|
+
<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@latest/dist/loader.min.js"></script>
|
|
1168
|
+
```
|
|
1169
|
+
|
|
1170
|
+
2. **Loader fetches** `version.json` to determine which widget version to load
|
|
1171
|
+
|
|
1172
|
+
3. **Loader dynamically loads** the appropriate widget version
|
|
1173
|
+
|
|
1174
|
+
4. **You publish a new version**:
|
|
1175
|
+
```bash
|
|
1176
|
+
npm run build # Automatically updates version.json
|
|
1177
|
+
npm publish
|
|
1178
|
+
```
|
|
1179
|
+
|
|
1180
|
+
5. **All clients automatically receive the new version** (within minutes, when CDN syncs)
|
|
1181
|
+
|
|
1182
|
+
### Configuration Options
|
|
1183
|
+
|
|
1184
|
+
#### Loader Attributes
|
|
1185
|
+
|
|
1186
|
+
| Attribute | Type | Default | Description |
|
|
1187
|
+
|-----------|------|---------|-------------|
|
|
1188
|
+
| `data-channel` | `'stable' \| 'beta'` | `'stable'` | Distribution channel |
|
|
1189
|
+
| `data-version` | `string` | `null` | Pin to specific version (disables auto-update) |
|
|
1190
|
+
| `data-debug` | `boolean` | `false` | Enable debug logging |
|
|
1191
|
+
| `data-api-url` | `string` | `null` | Analytics endpoint URL |
|
|
1192
|
+
|
|
1193
|
+
#### Examples
|
|
1194
|
+
|
|
1195
|
+
**Use beta channel:**
|
|
1196
|
+
```html
|
|
1197
|
+
<script
|
|
1198
|
+
src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@latest/dist/loader.min.js"
|
|
1199
|
+
data-channel="beta"
|
|
1200
|
+
></script>
|
|
1201
|
+
```
|
|
1202
|
+
|
|
1203
|
+
**Pin to specific version (no auto-update):**
|
|
1204
|
+
```html
|
|
1205
|
+
<script
|
|
1206
|
+
src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@latest/dist/loader.min.js"
|
|
1207
|
+
data-version="1.0.8"
|
|
1208
|
+
></script>
|
|
1209
|
+
```
|
|
1210
|
+
|
|
1211
|
+
**Enable debug mode:**
|
|
1212
|
+
```html
|
|
1213
|
+
<script
|
|
1214
|
+
src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@latest/dist/loader.min.js"
|
|
1215
|
+
data-debug="true"
|
|
1216
|
+
></script>
|
|
1217
|
+
```
|
|
1218
|
+
|
|
1219
|
+
### Loader Events
|
|
1220
|
+
|
|
1221
|
+
The loader emits custom events you can listen to:
|
|
1222
|
+
|
|
1223
|
+
```javascript
|
|
1224
|
+
// Widget loaded successfully
|
|
1225
|
+
window.addEventListener('tia-gpc-loader-ready', (event) => {
|
|
1226
|
+
console.log('Widget loaded:', event.detail);
|
|
1227
|
+
// event.detail = {
|
|
1228
|
+
// version: "1.0.9",
|
|
1229
|
+
// loadTime: 1234, // milliseconds
|
|
1230
|
+
// attempts: 1,
|
|
1231
|
+
// channel: "stable"
|
|
1232
|
+
// }
|
|
1233
|
+
});
|
|
1234
|
+
|
|
1235
|
+
// Widget failed to load
|
|
1236
|
+
window.addEventListener('tia-gpc-loader-error', (event) => {
|
|
1237
|
+
console.error('Widget error:', event.detail);
|
|
1238
|
+
// event.detail = {
|
|
1239
|
+
// error: "Failed to load...",
|
|
1240
|
+
// attempts: 3,
|
|
1241
|
+
// version: "1.0.9"
|
|
1242
|
+
// }
|
|
1243
|
+
});
|
|
1244
|
+
```
|
|
1245
|
+
|
|
1246
|
+
### Loader API
|
|
1247
|
+
|
|
1248
|
+
The loader exposes a global `TiaGPCLoader` object:
|
|
1249
|
+
|
|
1250
|
+
```javascript
|
|
1251
|
+
// Get loader version
|
|
1252
|
+
console.log(window.TiaGPCLoader.version); // "1.0.0"
|
|
1253
|
+
|
|
1254
|
+
// Reload widget
|
|
1255
|
+
window.TiaGPCLoader.reload();
|
|
1256
|
+
|
|
1257
|
+
// Get configuration
|
|
1258
|
+
console.log(window.TiaGPCLoader.config);
|
|
1259
|
+
```
|
|
1260
|
+
|
|
1261
|
+
### Version Control with version.json
|
|
1262
|
+
|
|
1263
|
+
The `version.json` file controls which version is served to clients:
|
|
1264
|
+
|
|
1265
|
+
```json
|
|
1266
|
+
{
|
|
1267
|
+
"version": "1.0.9",
|
|
1268
|
+
"stable": {
|
|
1269
|
+
"version": "1.0.9",
|
|
1270
|
+
"js": "https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.9/dist/tia-gpc-widget.standalone.js",
|
|
1271
|
+
"css": "https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.9/dist/tia-gpc-widget.standalone.css",
|
|
1272
|
+
"cdn": "jsdelivr"
|
|
1273
|
+
},
|
|
1274
|
+
"beta": {
|
|
1275
|
+
"version": "1.1.0-beta",
|
|
1276
|
+
"js": "https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.1.0-beta/dist/tia-gpc-widget.standalone.js",
|
|
1277
|
+
"css": "https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.1.0-beta/dist/tia-gpc-widget.standalone.css",
|
|
1278
|
+
"cdn": "jsdelivr"
|
|
1279
|
+
}
|
|
1280
|
+
}
|
|
1281
|
+
```
|
|
1282
|
+
|
|
1283
|
+
This file is automatically generated when you run `npm run build`.
|
|
1284
|
+
|
|
1285
|
+
### Deployment Workflow
|
|
1286
|
+
|
|
1287
|
+
#### Before (without loader):
|
|
1288
|
+
```bash
|
|
1289
|
+
# 1. Make changes to widget
|
|
1290
|
+
# 2. Build
|
|
1291
|
+
npm run build
|
|
1292
|
+
|
|
1293
|
+
# 3. Publish to npm
|
|
1294
|
+
npm publish
|
|
1295
|
+
|
|
1296
|
+
# ❌ Clients must manually update their code:
|
|
1297
|
+
# <script src="...@1.0.6/..."></script> → <script src="...@1.0.7/..."></script>
|
|
1298
|
+
```
|
|
1299
|
+
|
|
1300
|
+
#### After (with loader):
|
|
1301
|
+
```bash
|
|
1302
|
+
# 1. Make changes to widget
|
|
1303
|
+
# 2. Build (automatically updates version.json)
|
|
1304
|
+
npm run build
|
|
1305
|
+
|
|
1306
|
+
# 3. Publish to npm
|
|
1307
|
+
npm publish
|
|
1308
|
+
|
|
1309
|
+
# ✅ All clients automatically receive the new version!
|
|
1310
|
+
# No manual updates required!
|
|
1311
|
+
```
|
|
1312
|
+
|
|
1313
|
+
### Advanced: Gradual Rollout
|
|
1314
|
+
|
|
1315
|
+
You can manually edit `version.json` to implement gradual rollouts:
|
|
1316
|
+
|
|
1317
|
+
```json
|
|
1318
|
+
{
|
|
1319
|
+
"stable": {
|
|
1320
|
+
"version": "1.0.9",
|
|
1321
|
+
"rollout": {
|
|
1322
|
+
"percentage": 50, // Only 50% of users get this version
|
|
1323
|
+
"whitelist": ["client-id-1", "client-id-2"],
|
|
1324
|
+
"blacklist": ["problematic-client"]
|
|
1325
|
+
}
|
|
1326
|
+
}
|
|
1327
|
+
}
|
|
1328
|
+
```
|
|
1329
|
+
|
|
1330
|
+
Note: Rollout logic must be implemented on your backend.
|
|
1331
|
+
|
|
1332
|
+
### Migration Guide
|
|
1333
|
+
|
|
1334
|
+
#### Migrating from Direct CDN Links
|
|
1335
|
+
|
|
1336
|
+
**Before:**
|
|
1337
|
+
```html
|
|
1338
|
+
<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.js"></script>
|
|
1339
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.6/dist/tia-gpc-widget.standalone.css">
|
|
1340
|
+
|
|
1341
|
+
<tia-gpc-widget token="xxx"></tia-gpc-widget>
|
|
1342
|
+
```
|
|
1343
|
+
|
|
1344
|
+
**After:**
|
|
1345
|
+
```html
|
|
1346
|
+
<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@latest/dist/loader.min.js"></script>
|
|
1347
|
+
|
|
1348
|
+
<tia-gpc-widget token="xxx"></tia-gpc-widget>
|
|
1349
|
+
```
|
|
1350
|
+
|
|
1351
|
+
That's it! The loader handles everything else.
|
|
1352
|
+
|
|
1353
|
+
### Troubleshooting
|
|
1354
|
+
|
|
1355
|
+
#### Loader not loading widget
|
|
1356
|
+
|
|
1357
|
+
1. Open browser console and check for errors
|
|
1358
|
+
2. Enable debug mode: `data-debug="true"`
|
|
1359
|
+
3. Check network tab for failed requests
|
|
1360
|
+
4. Verify `version.json` is accessible
|
|
1361
|
+
|
|
1362
|
+
#### Widget not updating
|
|
1363
|
+
|
|
1364
|
+
1. Clear browser cache
|
|
1365
|
+
2. Check that `version.json` has the correct version
|
|
1366
|
+
3. Wait for CDN to sync (can take 5-10 minutes)
|
|
1367
|
+
4. Check if client is using `data-version` (which pins to specific version)
|
|
1368
|
+
|
|
1369
|
+
#### Using with Content Security Policy (CSP)
|
|
1370
|
+
|
|
1371
|
+
If your site uses CSP, you may need to add:
|
|
1372
|
+
|
|
1373
|
+
```html
|
|
1374
|
+
<meta http-equiv="Content-Security-Policy" content="
|
|
1375
|
+
script-src 'self' https://cdn.jsdelivr.net https://unpkg.com;
|
|
1376
|
+
style-src 'self' https://cdn.jsdelivr.net https://unpkg.com;
|
|
1377
|
+
connect-src 'self' https://cdn.jsdelivr.net https://unpkg.com;
|
|
1378
|
+
">
|
|
1379
|
+
```
|
|
1380
|
+
|
|
1381
|
+
### Examples
|
|
1382
|
+
|
|
1383
|
+
See complete examples in the `/examples` folder:
|
|
1384
|
+
- `examples/loader-usage.html` - Complete loader demo with all features
|
|
1385
|
+
|
|
1386
|
+
---
|
|
1387
|
+
|
|
1388
|
+
**Built with ❤️ by the TIA team**
|