tia-gpc-widget-prod

v3.0.9

Published

10 days ago

Widget TIA GPC - Compatible con React, HTML puro, Angular, ASP.NET y cualquier framework

0High
0Medium
0Low

softiatechnologiesinc

tia gpc widget react angular web-component vanilla-js html aspnet framework-agnostic chat ai medical chatbot

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

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

Quick Start with Loader

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My App with TIA GPC</title>
</head>
<body>
  <h1>My Application</h1>

  <!-- TIA GPC Widget Loader (install once, updates forever) -->
  <script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget-prod@latest/dist/loader.min.js"></script>

  <!-- Widget element -->
  <tia-gpc-widget-prod
    token="your-license-token-here"
    theme="auto"
    position="bottom-right"
    language="en"
  ></tia-gpc-widget-prod>
</body>
</html>

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

Option 1: Auto-Update Loader (Recommended)

Use the loader for automatic updates:

<!-- jsDelivr (Recommended) -->
<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget-prod@latest/dist/loader.min.js"></script>

<!-- unpkg -->
<script src="https://unpkg.com/tia-gpc-widget-prod@latest/dist/loader.min.js"></script>

Then use the widget as normal:

<tia-gpc-widget-prod token="your-token" theme="auto"></tia-gpc-widget-prod>

Option 2: NPM (For React/Node Projects)

npm install tia-gpc-widget-prod

or with yarn:

yarn add tia-gpc-widget-prod

or with pnpm:

pnpm add tia-gpc-widget-prod

Option 3: Direct CDN (Legacy - Not Recommended)

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

<!-- ⚠️ Legacy method: Requires manual version updates -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/tia-gpc-widget-prod.standalone.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/tia-gpc-widget-prod.standalone.css">

unpkg - Fixed Version

<!-- ⚠️ Legacy method: Requires manual version updates -->
<script src="https://unpkg.com/[email protected]/dist/tia-gpc-widget-prod.standalone.js"></script>
<link rel="stylesheet" href="https://unpkg.com/[email protected]/dist/tia-gpc-widget-prod.standalone.css">

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

In Plain HTML

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My App with TIA GPC</title>
</head>
<body>
  <h1>My Application</h1>

  <!-- TIA GPC Widget -->
  <tia-gpc-widget-prod
    token="your-license-token-here"
    theme="auto"
    position="bottom-right"
    language="en"
  ></tia-gpc-widget-prod>

  <!-- Auto-Update Loader (loads latest version automatically) -->
  <script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget-prod@latest/dist/loader.min.js"></script>
</body>
</html>

In React

import { TiaGPCWidget } from 'tia-gpc-widget-prod';
import 'tia-gpc-widget-prod/styles';

function App() {
  return (
    <div>
      <h1>My Application</h1>
      <TiaGPCWidget
        token="your-license-token-here"
        theme="auto"
        position="bottom-right"
        language="en"
      />
    </div>
  );
}

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.

1. React

Installation

npm install tia-gpc-widget-prod

Basic Usage

import { TiaGPCWidget } from 'tia-gpc-widget-prod';
import 'tia-gpc-widget-prod/styles';

function App() {
  return (
    <TiaGPCWidget
      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

import { TiaGPCWidget, WIDGET_POSITIONS, THEMES, LANGUAGES } from 'tia-gpc-widget-prod';
import 'tia-gpc-widget-prod/styles';

function App() {
  const handleReady = () => {
    console.log('✅ Widget initialized successfully');
  };

  const handleError = (error) => {
    console.error('❌ Widget error:', error);
  };

  return (
    <TiaGPCWidget
      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')}
    />
  );
}

2. HTML / Vanilla JavaScript

Method 1: Using HTML element directly

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>TIA GPC Widget - Plain HTML</title>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/tia-gpc-widget-prod.standalone.css">
</head>
<body>
  <h1>My Website</h1>

  <!-- Widget as HTML element -->
  <tia-gpc-widget-prod
    token="your-license-token"
    theme="light"
    position="bottom-right"
    language="en"
    primary-color="#3b82f6"
    width="400px"
    height="600px"
    auto-open="false"
    show-branding="true"
  ></tia-gpc-widget-prod>

  <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/tia-gpc-widget-prod.standalone.js"></script>

  <!-- Optional events -->
  <script>
    const widget = document.querySelector('tia-gpc-widget-prod');

    widget.addEventListener('ready', () => {
      console.log('Widget ready');
    });

    widget.addEventListener('error', (e) => {
      console.error('Error:', e.detail);
    });

    widget.addEventListener('close', () => {
      console.log('Widget closed');
    });
  </script>
</body>
</html>

Method 2: Programmatic creation with JavaScript

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>TIA GPC Widget - Programmatic</title>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/tia-gpc-widget-prod.standalone.css">
</head>
<body>
  <h1>My Website</h1>
  <button id="create-widget">Create Widget</button>

  <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/tia-gpc-widget-prod.standalone.js"></script>
  <script>
    document.getElementById('create-widget').addEventListener('click', () => {
      // Use the global TiaGPC API
      const widget = TiaGPC.create({
        token: 'your-license-token',
        theme: 'auto',
        position: TiaGPC.POSITIONS.BOTTOM_RIGHT,
        language: TiaGPC.LANGUAGES.EN,
        primaryColor: '#3b82f6',
        autoOpen: false,
        onReady: () => console.log('✅ Widget ready'),
        onError: (error) => console.error('❌ Error:', error),
        onClose: () => console.log('Widget closed')
      });

      console.log('Widget created:', widget);
    });

    // View widget information
    TiaGPC.info();
  </script>
</body>
</html>

3. Angular

Step 1: Install the widget

npm install tia-gpc-widget-prod

Step 2: Configure Angular for Web Components

In src/main.ts or src/polyfills.ts, add:

// Enable Custom Elements (Web Components)
import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

In your main module (app.module.ts):

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:

{
  "projects": {
    "your-project": {
      "architect": {
        "build": {
          "options": {
            "styles": [
              "src/styles.css",
              "node_modules/tia-gpc-widget-prod/dist/tia-gpc-widget-prod.standalone.css"
            ],
            "scripts": [
              "node_modules/tia-gpc-widget-prod/dist/tia-gpc-widget-prod.standalone.js"
            ]
          }
        }
      }
    }
  }
}

Step 4: Use the widget in your component

// app.component.ts
import { Component, OnInit } from '@angular/core';

declare global {
  interface Window {
    TiaGPC: any;
  }
}

@Component({
  selector: 'app-root',
  template: `
    <h1>My Angular Application</h1>

    <!-- Option 1: Direct HTML element -->
    <tia-gpc-widget-prod
      [attr.token]="widgetToken"
      [attr.theme]="theme"
      [attr.position]="position"
      [attr.language]="language"
      (ready)="onWidgetReady()"
      (error)="onWidgetError($event)"
    ></tia-gpc-widget-prod>
  `
})
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

// app.component.ts
import { Component, OnInit } from '@angular/core';

@Component({
  selector: 'app-root',
  template: `
    <h1>My Angular Application</h1>
    <button (click)="createWidget()">Create Widget</button>
    <div #widgetContainer></div>
  `
})
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)
      });
    }
  }
}

4. ASP.NET / ASPX

Option 1: In an ASPX page

<%@ Page Language="C#" AutoEventWireup="true" %>

<!DOCTYPE html>
<html>
<head>
    <title>TIA GPC Widget - ASP.NET</title>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/tia-gpc-widget-prod.standalone.css" />
</head>
<body>
    <form id="form1" runat="server">
        <h1>My ASP.NET Application</h1>

        <!-- TIA GPC Widget -->
        <tia-gpc-widget-prod
            token="<%= ConfigurationManager.AppSettings["TiaGpcToken"] %>"
            theme="auto"
            position="bottom-right"
            language="en"
            primary-color="#2563eb"
        ></tia-gpc-widget-prod>
    </form>

    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/tia-gpc-widget-prod.standalone.js"></script>
    <script>
        // Optional events
        document.querySelector('tia-gpc-widget-prod').addEventListener('ready', function() {
            console.log('TIA GPC Widget initialized');
        });
    </script>
</body>
</html>

Option 2: With Master Page

In your Site.Master:

<head runat="server">
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/tia-gpc-widget-prod.standalone.css" />
</head>
<body>
    <asp:ContentPlaceHolder ID="MainContent" runat="server">
    </asp:ContentPlaceHolder>

    <!-- Global widget -->
    <tia-gpc-widget-prod
        token="<%= GetTiaGpcToken() %>"
        theme="auto"
        language="en"
    ></tia-gpc-widget-prod>

    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/tia-gpc-widget-prod.standalone.js"></script>
</body>

In your Site.Master.cs:

public partial class SiteMaster : MasterPage
{
    protected string GetTiaGpcToken()
    {
        return ConfigurationManager.AppSettings["TiaGpcToken"];
    }
}

Option 3: MVC / Razor

In your layout _Layout.cshtml:

<!DOCTYPE html>
<html>
<head>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/tia-gpc-widget-prod.standalone.css" />
</head>
<body>
    @RenderBody()

    <!-- TIA GPC Widget -->
    <tia-gpc-widget-prod
        token="@ViewBag.TiaGpcToken"
        theme="auto"
        language="en"
    ></tia-gpc-widget-prod>

    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/tia-gpc-widget-prod.standalone.js"></script>
</body>
</html>

In your Controller:

public class HomeController : Controller
{
    public ActionResult Index()
    {
        ViewBag.TiaGpcToken = ConfigurationManager.AppSettings["TiaGpcToken"];
        return View();
    }
}

5. Vue.js

Installation

npm install tia-gpc-widget-prod

Configuration

In main.js or main.ts:

import { createApp } from 'vue';
import App from './App.vue';

// Import the standalone widget
import 'tia-gpc-widget-prod/dist/tia-gpc-widget-prod.standalone.js';
import 'tia-gpc-widget-prod/dist/tia-gpc-widget-prod.standalone.css';

const app = createApp(App);

// Configure Vue to ignore custom elements
app.config.compilerOptions.isCustomElement = (tag) => tag === 'tia-gpc-widget-prod';

app.mount('#app');

Usage in components

<template>
  <div>
    <h1>My Vue Application</h1>

    <!-- TIA GPC Widget -->
    <tia-gpc-widget-prod
      :token="widgetToken"
      :theme="theme"
      :language="language"
      position="bottom-right"
      @ready="onReady"
      @error="onError"
    ></tia-gpc-widget-prod>
  </div>
</template>

<script setup>
import { ref, onMounted } from 'vue';

const widgetToken = ref('your-license-token');
const theme = ref('auto');
const language = ref('en');

const onReady = () => {
  console.log('✅ TIA GPC Widget ready');
};

const onError = (event) => {
  console.error('❌ Error:', event.detail);
};

onMounted(() => {
  console.log('TiaGPC available:', window.TiaGPC);
});
</script>

6. Next.js

Installation

npm install tia-gpc-widget-prod

Usage (with Client Component)

// 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-prod/dist/tia-gpc-widget-prod.standalone.js');
  }, []);

  return (
    <>
      {/* CSS */}
      <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/tia-gpc-widget-prod.standalone.css" />

      {/* Widget */}
      <tia-gpc-widget-prod
        token={process.env.NEXT_PUBLIC_TIA_GPC_TOKEN}
        theme="auto"
        language="en"
      ></tia-gpc-widget-prod>
    </>
  );
}

In your page:

// app/page.jsx
import TiaWidget from '@/components/TiaWidget';

export default function Home() {
  return (
    <main>
      <h1>My Next.js App</h1>
      <TiaWidget />
    </main>
  );
}

7. PHP

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>TIA GPC Widget - PHP</title>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/tia-gpc-widget-prod.standalone.css">
</head>
<body>
    <h1>My PHP Application</h1>

    <?php
    // Get token from environment variables or config
    $tiaGpcToken = getenv('TIA_GPC_TOKEN') ?: 'your-license-token';
    $userLanguage = $_SESSION['user_language'] ?? 'en';
    ?>

    <!-- TIA GPC Widget -->
    <tia-gpc-widget-prod
        token="<?php echo htmlspecialchars($tiaGpcToken); ?>"
        theme="auto"
        position="bottom-right"
        language="<?php echo htmlspecialchars($userLanguage); ?>"
    ></tia-gpc-widget-prod>

    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/tia-gpc-widget-prod.standalone.js"></script>
</body>
</html>

🎛️ API & Configuration

Props/Attributes

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 |

Events

| 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

<script>
  const widget = document.querySelector('tia-gpc-widget-prod');

  widget.addEventListener('ready', () => {
    console.log('Widget ready');
  });

  widget.addEventListener('error', (e) => {
    console.error('Error:', e.detail);
    // Send to logging system
  });

  widget.addEventListener('close', () => {
    console.log('User closed the widget');
    // Analytics or tracking
  });
</script>

Programmatic API (JavaScript)

The widget exposes a global TiaGPC API for programmatic control:

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

Themes

<!-- Automatic (follows system preferences) -->
<tia-gpc-widget-prod theme="auto"></tia-gpc-widget-prod>

<!-- Light -->
<tia-gpc-widget-prod theme="light"></tia-gpc-widget-prod>

<!-- Dark -->
<tia-gpc-widget-prod theme="dark"></tia-gpc-widget-prod>

Positions

<!-- Bottom right corner (default) -->
<tia-gpc-widget-prod position="bottom-right"></tia-gpc-widget-prod>

<!-- Bottom left corner -->
<tia-gpc-widget-prod position="bottom-left"></tia-gpc-widget-prod>

<!-- Top right corner -->
<tia-gpc-widget-prod position="top-right"></tia-gpc-widget-prod>

<!-- Top left corner -->
<tia-gpc-widget-prod position="top-left"></tia-gpc-widget-prod>

Languages

<!-- Spanish -->
<tia-gpc-widget-prod language="es"></tia-gpc-widget-prod>

<!-- English -->
<tia-gpc-widget-prod language="en"></tia-gpc-widget-prod>

<!-- French -->
<tia-gpc-widget-prod language="fr"></tia-gpc-widget-prod>

Colors

<!-- Custom color -->
<tia-gpc-widget-prod
  primary-color="#10b981"
></tia-gpc-widget-prod>

<!-- Blue (default) -->
<tia-gpc-widget-prod primary-color="#2563eb"></tia-gpc-widget-prod>

<!-- Green -->
<tia-gpc-widget-prod primary-color="#16a34a"></tia-gpc-widget-prod>

<!-- Purple -->
<tia-gpc-widget-prod primary-color="#9333ea"></tia-gpc-widget-prod>

🛠️ Build & Development

Available scripts

# 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

Generated file structure

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-prod.standalone.js   # Standalone build (IIFE with React)
└── tia-gpc-widget-prod.standalone.css  # CSS for standalone

Which file to use?

| 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-prod.standalone.js + tia-gpc-widget-prod.standalone.css |

📤 Publishing

Publish to NPM (Public)

# 1. Login to NPM
npm login

# 2. Build the project
npm run build

# 3. Publish
npm publish

Publish to Private NPM / GitLab Package Registry

Configure `.npmrc`

Create an .npmrc file in the project root:

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

{
  "name": "@your-scope/tia-gpc-widget-prod",
  "publishConfig": {
    "@your-scope:registry": "https://gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/"
  }
}

Publish

npm run build
npm publish

CDN Distribution

After publishing to npm, your package is automatically available on these CDNs:

jsDelivr

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/tia-gpc-widget-prod.standalone.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/tia-gpc-widget-prod.standalone.css">

unpkg

<script src="https://unpkg.com/[email protected]/dist/tia-gpc-widget-prod.standalone.js"></script>
<link rel="stylesheet" href="https://unpkg.com/[email protected]/dist/tia-gpc-widget-prod.standalone.css">

Note: CDNs may take 5-10 minutes to sync after publishing to npm.

Manual Distribution

Copy files from dist/ to your web server:

# Copy standalone files to server
cp dist/tia-gpc-widget-prod.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: [email protected]
Web: https://tia.com/gpc

📊 Bundle Sizes

| File | Size (gzip) | Description | |---------|---------------|-------------| | tia-gpc.es.js | ~45 KB | NPM build (without React) | | tia-gpc-widget-prod.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

Widget doesn't appear

Verify you included both files (JS and CSS)
Check browser console for errors
Make sure the token is valid

Error: "customElements.define() called with incorrect arguments"

In Angular: Add CUSTOM_ELEMENTS_SCHEMA to your module
In Vue: Configure isCustomElement in compiler options

CSS Conflicts

The widget uses gpc- prefixes on all classes to avoid conflicts. If there are still issues, you can increase specificity:

.your-container tia-gpc-widget-prod {
  /* your custom styles */
}

React is not defined (in standalone build)

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: [email protected]
GitLab Issues: https://gitlab.com/softia/tiagpc-frontend/issues
Documentation: This README

🚀 Changelog

v1.0.6 (2025-01-11)

✨ Added CDN support via jsDelivr and unpkg
📝 Updated documentation to English
🔧 Added unpkg and jsdelivr fields to package.json

v1.0.0 (2025-01-10)

✨ 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

What is the Auto-Update Loader?

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

How it Works

Client installs the loader (one time only):

<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget-prod@latest/dist/loader.min.js"></script>

Loader fetches version.json to determine which widget version to load
Loader dynamically loads the appropriate widget version

You publish a new version:

npm run build  # Automatically updates version.json
npm publish

All clients automatically receive the new version (within minutes, when CDN syncs)

Configuration Options

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:

<script
  src="https://cdn.jsdelivr.net/npm/tia-gpc-widget-prod@latest/dist/loader.min.js"
  data-channel="beta"
></script>

Pin to specific version (no auto-update):

<script
  src="https://cdn.jsdelivr.net/npm/tia-gpc-widget-prod@latest/dist/loader.min.js"
  data-version="1.0.8"
></script>

Enable debug mode:

<script
  src="https://cdn.jsdelivr.net/npm/tia-gpc-widget-prod@latest/dist/loader.min.js"
  data-debug="true"
></script>

Loader Events

The loader emits custom events you can listen to:

// 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"
  // }
});

Loader API

The loader exposes a global TiaGPCLoader object:

// Get loader version
console.log(window.TiaGPCLoader.version);  // "1.0.0"

// Reload widget
window.TiaGPCLoader.reload();

// Get configuration
console.log(window.TiaGPCLoader.config);

Version Control with version.json

The version.json file controls which version is served to clients:

{
  "version": "1.0.9",
  "stable": {
    "version": "1.0.9",
    "js": "https://cdn.jsdelivr.net/npm/[email protected]/dist/tia-gpc-widget-prod.standalone.js",
    "css": "https://cdn.jsdelivr.net/npm/[email protected]/dist/tia-gpc-widget-prod.standalone.css",
    "cdn": "jsdelivr"
  },
  "beta": {
    "version": "1.1.0-beta",
    "js": "https://cdn.jsdelivr.net/npm/[email protected]/dist/tia-gpc-widget-prod.standalone.js",
    "css": "https://cdn.jsdelivr.net/npm/[email protected]/dist/tia-gpc-widget-prod.standalone.css",
    "cdn": "jsdelivr"
  }
}

This file is automatically generated when you run npm run build.

Deployment Workflow

Before (without loader):

# 1. Make changes to widget
# 2. Build
npm run build

# 3. Publish to npm
npm publish

# ❌ Clients must manually update their code:
# <script src="[email protected]/..."></script>  →  <script src="[email protected]/..."></script>

After (with loader):

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

Advanced: Gradual Rollout

You can manually edit version.json to implement gradual rollouts:

{
  "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.

Migration Guide

Migrating from Direct CDN Links

Before:

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/tia-gpc-widget-prod.standalone.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/tia-gpc-widget-prod.standalone.css">

<tia-gpc-widget-prod token="xxx"></tia-gpc-widget-prod>

After:

<script src="https://cdn.jsdelivr.net/npm/tia-gpc-widget-prod@latest/dist/loader.min.js"></script>

<tia-gpc-widget-prod token="xxx"></tia-gpc-widget-prod>

That's it! The loader handles everything else.

Troubleshooting

Loader not loading widget

Open browser console and check for errors
Enable debug mode: data-debug="true"
Check network tab for failed requests
Verify version.json is accessible

Widget not updating

Clear browser cache
Check that version.json has the correct version
Wait for CDN to sync (can take 5-10 minutes)
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:

<meta http-equiv="Content-Security-Policy" content="
  script-src 'self' https://cdn.jsdelivr.net https://unpkg.com;
  style-src 'self' https://cdn.jsdelivr.net https://unpkg.com;
  connect-src 'self' https://cdn.jsdelivr.net https://unpkg.com;
">

Examples

See complete examples in the /examples folder:

examples/loader-usage.html - Complete loader demo with all features

Built with ❤️ by the TIA team

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

TIA GPC Widget

📋 Table of Contents

🚀 Features

🚀 Auto-Update Loader (Recommended)

Quick Start with Loader

📦 Installation

Option 1: Auto-Update Loader (Recommended)

Option 2: NPM (For React/Node Projects)

Option 3: Direct CDN (Legacy - Not Recommended)

jsDelivr - Fixed Version

unpkg - Fixed Version

⚡ Quick Start

In Plain HTML

In React

📚 Framework Examples

1. React

Installation

Basic Usage

Advanced Configuration

2. HTML / Vanilla JavaScript

Method 1: Using HTML element directly

Method 2: Programmatic creation with JavaScript

3. Angular

Step 1: Install the widget

Step 2: Configure Angular for Web Components

Step 3: Import widget files

Step 4: Use the widget in your component

Alternative option: Programmatic creation

4. ASP.NET / ASPX

Option 1: In an ASPX page

Option 2: With Master Page

Option 3: MVC / Razor

5. Vue.js

Installation

Configuration

Usage in components

6. Next.js

Installation

Usage (with Client Component)

7. PHP

🎛️ API & Configuration

Props/Attributes

Events

Event usage example

Programmatic API (JavaScript)

🎨 Customization

Themes

Positions

Languages

Colors

🛠️ Build & Development

Available scripts

Generated file structure

Which file to use?

📤 Publishing

Publish to NPM (Public)

Publish to Private NPM / GitLab Package Registry

Configure .npmrc

Update package.json

Publish

CDN Distribution

jsDelivr

unpkg

Manual Distribution

🔐 Getting a License Token

📊 Bundle Sizes

🐛 Troubleshooting

Widget doesn't appear

Error: "customElements.define() called with incorrect arguments"

CSS Conflicts

React is not defined (in standalone build)

📝 License

👥 Support

🚀 Changelog

Configure `.npmrc`

Update `package.json`