TIA GPC Widget

Intelligent chat widget for TIA GPC integration. Compatible with React, HTML, Angular, ASP.NET, Vue, and any other framework.


---

📋 Table of Contents

- Features
- Installation
- Option 1: NPM (For React/Node Projects)
- Option 2: CDN (For HTML, Angular, ASP.NET, etc.)
- Quick Start
- Framework Examples
- React
- HTML / Vanilla JavaScript
- Angular
- ASP.NET / ASPX
- Vue.js
- Next.js
- PHP
- API & Configuration
- Props/Attributes
- Events
- Programmatic API (JavaScript)
- Customization
- Themes
- Positions
- Languages
- Colors
- Build & Development
- Publishing
- Support

---

🚀 Features

- ✅ Framework Agnostic: Works in React, Angular, Vue, ASP.NET, plain HTML, etc.
- ✅ Web Component: Based on native web standards
- ✅ Themes: Light, dark, or automatic mode
- ✅ Internationalization: Spanish, English, French
- ✅ Responsive: Adaptive design for mobile and desktop
- ✅ Customizable: Colors, positions, dimensions
- ✅ TypeScript Ready: Types included
- ✅ Zero Dependencies: Standalone bundle includes everything needed

---

🚀 Auto-Update Loader (Recommended)

NEW! Install once, get updates forever. No more manual version updates!

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.

$3

``html

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 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

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

My Website

Create Widget





`

---

$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:

My Angular Application

[attr.token]="widgetToken"
[attr.theme]="theme"
[attr.position]="position"
[attr.language]="language"
(ready)="onWidgetReady()"
(error)="onWidgetError($event)"
>

})
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:

My Angular Application

Create Widget


})
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" %>

My ASP.NET Application

token="<%= ConfigurationManager.AppSettings["TiaGpcToken"] %>"
theme="auto"
position="bottom-right"
language="en"
primary-color="#2563eb"
>

`

#### 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



`

---

$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

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

`

Pin to specific version (no auto-update):
`html

`

Enable debug mode:
`html

`

$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

---

Built with ❤️ by the TIA team