Widget TIA GPC - Compatible con React, HTML puro, Angular, ASP.NET y cualquier framework
html
My App with TIA GPC
My Application
token="your-license-token-here"
theme="auto"
position="bottom-right"
language="en"
>
`
Benefits:
- ā
Install once, never update manually again
- ā
Automatic updates when you publish new versions
- ā
Built-in error handling and retries
- ā
Support for stable/beta channels
- ā
Extremely small (~1KB gzipped)
- ā
Works with all frameworks (HTML, React, Angular, ASP.NET, etc.)
See complete loader documentation and examples ā
---
š¦ Installation
$3
Use the loader for automatic updates:
`html
`
Then use the widget as normal:
`html
`
$3
`bash
npm install tia-gpc-widget
`
or with yarn:
`bash
yarn add tia-gpc-widget
`
or with pnpm:
`bash
pnpm add tia-gpc-widget
`
$3
ā ļø Note: This method is still supported but not recommended for new installations.
It requires manual updates every time we release a new version.
Use the Auto-Update Loader instead (see Option 1 above).
#### jsDelivr - Fixed Version
`html
`
#### unpkg - Fixed Version
`html
`
Why use the loader instead?
- ā
Automatic updates - no code changes needed
- ā
Always get bug fixes and improvements
- ā
Smaller initial load (~2KB vs ~420KB until needed)
- ā
Built-in error handling and fallbacks
For existing installations: See Migration Guide to upgrade to the auto-update loader.
---
ā” Quick Start
$3
`html
My App with TIA GPC
My Application
token="your-license-token-here"
theme="auto"
position="bottom-right"
language="en"
>
`
$3
`jsx
import { TiaGPCWidget } from 'tia-gpc-widget';
import 'tia-gpc-widget/styles';
function App() {
return (
My Application
token="your-license-token-here"
theme="auto"
position="bottom-right"
language="en"
/>
);
}
export default App;
`
---
š Framework Examples
> š” Important: The examples below may show both installation methods:
> - Recommended: Auto-Update Loader (install once, updates automatically)
> - Legacy: Direct CDN with fixed version (requires manual updates)
>
> For new installations, always use the Auto-Update Loader shown in Option 1.
$3
#### Installation
`bash
npm install tia-gpc-widget
`
#### Basic Usage
`jsx
import { TiaGPCWidget } from 'tia-gpc-widget';
import 'tia-gpc-widget/styles';
function App() {
return (
token="your-license-token"
theme="auto"
position="bottom-right"
language="en"
primaryColor="#2563eb"
onReady={() => console.log('Widget ready')}
onError={(error) => console.error('Error:', error)}
/>
);
}
`
#### Advanced Configuration
`jsx
import { TiaGPCWidget, WIDGET_POSITIONS, THEMES, LANGUAGES } from 'tia-gpc-widget';
import 'tia-gpc-widget/styles';
function App() {
const handleReady = () => {
console.log('ā
Widget initialized successfully');
};
const handleError = (error) => {
console.error('ā Widget error:', error);
};
return (
token="your-license-token"
theme={THEMES.AUTO}
position={WIDGET_POSITIONS.BOTTOM_RIGHT}
language={LANGUAGES.EN}
primaryColor="#10b981"
width="450px"
height="650px"
autoOpen={false}
showBranding={true}
mobileFullscreen={true}
onReady={handleReady}
onError={handleError}
onClose={() => console.log('Widget closed')}
/>
);
}
`
---
$3
#### Method 1: Using HTML element directly
`html
TIA GPC Widget - Plain HTML
My Website
token="your-license-token"
theme="light"
position="bottom-right"
language="en"
primary-color="#3b82f6"
width="400px"
height="600px"
auto-open="false"
show-branding="true"
>
`
#### Method 2: Programmatic creation with JavaScript
`html
TIA GPC Widget - Programmatic
My Website
`
---
$3
#### Step 1: Install the widget
`bash
npm install tia-gpc-widget
`
#### Step 2: Configure Angular for Web Components
In src/main.ts or src/polyfills.ts, add:
`typescript
// Enable Custom Elements (Web Components)
import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
`
In your main module (app.module.ts):
`typescript
import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppComponent } from './app.component';
@NgModule({
declarations: [AppComponent],
imports: [BrowserModule],
schemas: [CUSTOM_ELEMENTS_SCHEMA], // ā Important
bootstrap: [AppComponent]
})
export class AppModule { }
`
#### Step 3: Import widget files
In angular.json, add the CSS and JS files:
`json
{
"projects": {
"your-project": {
"architect": {
"build": {
"options": {
"styles": [
"src/styles.css",
"node_modules/tia-gpc-widget/dist/tia-gpc-widget.standalone.css"
],
"scripts": [
"node_modules/tia-gpc-widget/dist/tia-gpc-widget.standalone.js"
]
}
}
}
}
}
}
`
#### Step 4: Use the widget in your component
`typescript
// app.component.ts
import { Component, OnInit } from '@angular/core';
declare global {
interface Window {
TiaGPC: any;
}
}
@Component({
selector: 'app-root',
template:
})
export class AppComponent implements OnInit {
widgetToken = 'your-license-token';
theme = 'auto';
position = 'bottom-right';
language = 'en';
ngOnInit() {
console.log('TiaGPC available:', window.TiaGPC);
}
onWidgetReady() {
console.log('ā
TIA GPC widget ready');
}
onWidgetError(event: any) {
console.error('ā Widget error:', event.detail);
}
}
`
#### Alternative option: Programmatic creation
`typescript
// app.component.ts
import { Component, OnInit } from '@angular/core';
@Component({
selector: 'app-root',
template:
})
export class AppComponent implements OnInit {
ngOnInit() {
this.createWidget();
}
createWidget() {
if (window.TiaGPC) {
window.TiaGPC.create({
token: 'your-license-token',
theme: 'auto',
language: 'en',
onReady: () => console.log('Widget ready'),
onError: (err: any) => console.error(err)
});
}
}
}
`
---
$3
#### Option 1: In an ASPX page
`aspx
<%@ Page Language="C#" AutoEventWireup="true" %>
TIA GPC Widget - ASP.NET
`
#### Option 2: With Master Page
In your Site.Master:
`aspx
token="<%= GetTiaGpcToken() %>"
theme="auto"
language="en"
>
`
In your Site.Master.cs:
`csharp
public partial class SiteMaster : MasterPage
{
protected string GetTiaGpcToken()
{
return ConfigurationManager.AppSettings["TiaGpcToken"];
}
}
`
#### Option 3: MVC / Razor
In your layout _Layout.cshtml:
`html
@RenderBody()
token="@ViewBag.TiaGpcToken"
theme="auto"
language="en"
>
`
In your Controller:
`csharp
public class HomeController : Controller
{
public ActionResult Index()
{
ViewBag.TiaGpcToken = ConfigurationManager.AppSettings["TiaGpcToken"];
return View();
}
}
`
---
$3
#### Installation
`bash
npm install tia-gpc-widget
`
#### Configuration
In main.js or main.ts:
`javascript
import { createApp } from 'vue';
import App from './App.vue';
// Import the standalone widget
import 'tia-gpc-widget/dist/tia-gpc-widget.standalone.js';
import 'tia-gpc-widget/dist/tia-gpc-widget.standalone.css';
const app = createApp(App);
// Configure Vue to ignore custom elements
app.config.compilerOptions.isCustomElement = (tag) => tag === 'tia-gpc-widget';
app.mount('#app');
`
#### Usage in components
`vue
My Vue Application
:token="widgetToken"
:theme="theme"
:language="language"
position="bottom-right"
@ready="onReady"
@error="onError"
>
`
---
$3
#### Installation
`bash
npm install tia-gpc-widget
`
#### Usage (with Client Component)
`jsx
// components/TiaWidget.jsx
'use client'; // ā Important: Client Component
import { useEffect } from 'react';
export default function TiaWidget() {
useEffect(() => {
// Import widget only on client side
import('tia-gpc-widget/dist/tia-gpc-widget.standalone.js');
}, []);
return (
<>
{/ CSS /}
{/ Widget /}
token={process.env.NEXT_PUBLIC_TIA_GPC_TOKEN}
theme="auto"
language="en"
>
>
);
}
`
In your page:
`jsx
// app/page.jsx
import TiaWidget from '@/components/TiaWidget';
export default function Home() {
return (
My Next.js App
);
}
`
---
$3
`php
TIA GPC Widget - PHP
My PHP Application
// Get token from environment variables or config
$tiaGpcToken = getenv('TIA_GPC_TOKEN') ?: 'your-license-token';
$userLanguage = $_SESSION['user_language'] ?? 'en';
?>
token=""
theme="auto"
position="bottom-right"
language=""
>
`
---
šļø API & Configuration
$3
All frameworks support the same attributes:
| Attribute | Type | Default | Description |
|----------|------|-------------|-------------|
| token | string | Required | TIA GPC license token |
| theme | 'auto' \| 'light' \| 'dark' | 'auto' | Widget theme |
| position | 'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' | 'bottom-right' | Screen position |
| language | 'es' \| 'en' \| 'fr' | 'es' | Widget language |
| primary-color | string | '#2563eb' | Primary color (hexadecimal) |
| width | string | '400px' | Widget width |
| height | string | '600px' | Widget height |
| api-url | string | Default API | Custom API URL |
| turnstile-site-key | string | - | Cloudflare Turnstile site key |
| auto-open | boolean | false | Auto-open on load |
| show-branding | boolean | true | Show TIA GPC branding |
| mobile-fullscreen | boolean | true | Fullscreen on mobile |
$3
| Event | Description | Payload |
|--------|-------------|---------|
| ready | Fired when widget is ready | - |
| error | Fired when an error occurs | { detail: ErrorObject } |
| close | Fired when widget closes | - |
#### Event usage example
`html
`
$3
The widget exposes a global TiaGPC API for programmatic control:
`javascript
// Create widget programmatically
const widget = TiaGPC.create({
token: 'your-token',
theme: 'dark',
language: 'en',
position: TiaGPC.POSITIONS.BOTTOM_LEFT,
onReady: () => console.log('Ready'),
onError: (err) => console.error(err)
});
// Open widget
widget.open();
// Close widget
widget.close();
// View information
TiaGPC.info();
// Available constants
console.log(TiaGPC.POSITIONS); // { BOTTOM_RIGHT, BOTTOM_LEFT, ... }
console.log(TiaGPC.THEMES); // { AUTO, LIGHT, DARK }
console.log(TiaGPC.LANGUAGES); // { ES, EN, FR }
`
---
šØ Customization
$3
`html
`
$3
`html
`
$3
`html
`
$3
`html
primary-color="#10b981"
>
`
---
š ļø Build & Development
$3
`bash
Development (dev mode with hot reload)
npm run dev
Complete build (NPM + Standalone)
npm run build
Build only for NPM (without bundled React)
npm run build:npm
Standalone build (with bundled React)
npm run build:standalone
Lint
npm run lint
Preview
npm run preview
`
$3
`
dist/
āāā tia-gpc.es.js # ESM build for NPM
āāā tia-gpc.cjs.js # CommonJS build for NPM
āāā tia-gpc.css # CSS for NPM build
āāā tia-gpc-widget.standalone.js # Standalone build (IIFE with React)
āāā tia-gpc-widget.standalone.css # CSS for standalone
`
$3
| Environment | File to use |
|---------|----------------|
| React, Vue (with build system) | tia-gpc.es.js + tia-gpc.css |
| Node.js CommonJS | tia-gpc.cjs.js + tia-gpc.css |
| Plain HTML, Angular, ASP.NET, PHP | tia-gpc-widget.standalone.js + tia-gpc-widget.standalone.css |
---
š¤ Publishing
$3
`bash
1. Login to NPM
npm login
2. Build the project
npm run build
3. Publish
npm publish
`
$3
#### Configure .npmrc
Create an .npmrc file in the project root:
`ini
For GitLab Package Registry
@your-scope:registry=https://gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/
//gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/:_authToken=${CI_JOB_TOKEN}
`
#### Update package.json
`json
{
"name": "@your-scope/tia-gpc-widget",
"publishConfig": {
"@your-scope:registry": "https://gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/"
}
}
`
#### Publish
`bash
npm run build
npm publish
`
$3
After publishing to npm, your package is automatically available on these CDNs:
#### jsDelivr
`html
`
#### unpkg
`html
`
Note: CDNs may take 5-10 minutes to sync after publishing to npm.
$3
Copy files from dist/ to your web server:
`bash
Copy standalone files to server
cp dist/tia-gpc-widget.standalone.* /var/www/html/assets/
`
---
š Getting a License Token
To use this widget you need a TIA GPC license token. Contact the TIA team to get your token:
- Email: support@tia.com
- Web: https://tia.com/gpc
---
š Bundle Sizes
| File | Size (gzip) | Description |
|---------|---------------|-------------|
| tia-gpc.es.js | ~45 KB | NPM build (without React) |
| tia-gpc-widget.standalone.js | ~180 KB | Standalone build (with React) |
| *.css | ~15 KB | Styles |
The standalone bundle is larger because it includes React and all dependencies.
---
š Troubleshooting
$3
1. Verify you included both files (JS and CSS)
2. Check browser console for errors
3. Make sure the token is valid
$3
- In Angular: Add CUSTOM_ELEMENTS_SCHEMA to your module
- In Vue: Configure isCustomElement in compiler options
$3
The widget uses gpc- prefixes on all classes to avoid conflicts. If there are still issues, you can increase specificity:
`css
.your-container tia-gpc-widget {
/ your custom styles /
}
`
$3
If you see this error, make sure you're using the standalone.js file and not the regular NPM build.
---
š License
UNLICENSED - Internal use by TIA
---
š„ Support
For technical support:
- Email: support@tia.com
- GitLab Issues: https://gitlab.com/softia/tiagpc-frontend/issues
- Documentation: This README
---
š Changelog
$3
- ⨠Added CDN support via jsDelivr and unpkg
- š Updated documentation to English
- š§ Added unpkg and jsdelivr fields to package.json
$3
- ⨠Initial release
- ā
React support
- ā
Standalone build for HTML/Angular/ASP.NET
- ā
Web Component API
- ā
Light/dark themes
- ā
Internationalization (ES/EN/FR)
- ā
Full customization
---
š Loader Advanced Usage
$3
The TIA GPC Widget Loader is a revolutionary approach to widget distribution that solves the update problem:
- Traditional approach: Clients must manually update the version number in their code every time you release
- Loader approach: Clients install once, you control which version they receive via version.json
$3
1. Client installs the loader (one time only):
`html
`
2. Loader fetches version.json to determine which widget version to load
3. Loader dynamically loads the appropriate widget version
4. You publish a new version:
`bash
npm run build # Automatically updates version.json
npm publish
`
5. All clients automatically receive the new version (within minutes, when CDN syncs)
$3
#### Loader Attributes
| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| data-channel | 'stable' \| 'beta' | 'stable' | Distribution channel |
| data-version | string | null | Pin to specific version (disables auto-update) |
| data-debug | boolean | false | Enable debug logging |
| data-api-url | string | null | Analytics endpoint URL |
#### Examples
Use beta channel:
`html
src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@latest/dist/loader.min.js"
data-channel="beta"
>
`
Pin to specific version (no auto-update):
`html
src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@latest/dist/loader.min.js"
data-version="1.0.8"
>
`
Enable debug mode:
`html
src="https://cdn.jsdelivr.net/npm/tia-gpc-widget@latest/dist/loader.min.js"
data-debug="true"
>
`
$3
The loader emits custom events you can listen to:
`javascript
// Widget loaded successfully
window.addEventListener('tia-gpc-loader-ready', (event) => {
console.log('Widget loaded:', event.detail);
// event.detail = {
// version: "1.0.9",
// loadTime: 1234, // milliseconds
// attempts: 1,
// channel: "stable"
// }
});
// Widget failed to load
window.addEventListener('tia-gpc-loader-error', (event) => {
console.error('Widget error:', event.detail);
// event.detail = {
// error: "Failed to load...",
// attempts: 3,
// version: "1.0.9"
// }
});
`
$3
The loader exposes a global TiaGPCLoader object:
`javascript
// Get loader version
console.log(window.TiaGPCLoader.version); // "1.0.0"
// Reload widget
window.TiaGPCLoader.reload();
// Get configuration
console.log(window.TiaGPCLoader.config);
`
$3
The version.json file controls which version is served to clients:
`json
{
"version": "1.0.9",
"stable": {
"version": "1.0.9",
"js": "https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.9/dist/tia-gpc-widget.standalone.js",
"css": "https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.0.9/dist/tia-gpc-widget.standalone.css",
"cdn": "jsdelivr"
},
"beta": {
"version": "1.1.0-beta",
"js": "https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.1.0-beta/dist/tia-gpc-widget.standalone.js",
"css": "https://cdn.jsdelivr.net/npm/tia-gpc-widget@1.1.0-beta/dist/tia-gpc-widget.standalone.css",
"cdn": "jsdelivr"
}
}
`
This file is automatically generated when you run npm run build.
$3
#### Before (without loader):
`bash
1. Make changes to widget
2. Build
npm run build
3. Publish to npm
npm publish
ā Clients must manually update their code:
ā
`
#### After (with loader):
`bash
1. Make changes to widget
2. Build (automatically updates version.json)
npm run build
3. Publish to npm
npm publish
ā
All clients automatically receive the new version!
No manual updates required!
`
$3
You can manually edit version.json to implement gradual rollouts:
`json
{
"stable": {
"version": "1.0.9",
"rollout": {
"percentage": 50, // Only 50% of users get this version
"whitelist": ["client-id-1", "client-id-2"],
"blacklist": ["problematic-client"]
}
}
}
`
Note: Rollout logic must be implemented on your backend.
$3
#### Migrating from Direct CDN Links
Before:
`html
`
After:
`html
`
That's it! The loader handles everything else.
$3
#### Loader not loading widget
1. Open browser console and check for errors
2. Enable debug mode: data-debug="true"
3. Check network tab for failed requests
4. Verify version.json is accessible
#### Widget not updating
1. Clear browser cache
2. Check that version.json has the correct version
3. Wait for CDN to sync (can take 5-10 minutes)
4. Check if client is using data-version (which pins to specific version)
#### Using with Content Security Policy (CSP)
If your site uses CSP, you may need to add:
`html
`
$3
See complete examples in the /examples folder:
- examples/loader-usage.html` - Complete loader demo with all features