Widget pro ověření telefonního čísla

Úvod

Widget pro ověření telefonního čísla je nástroj, který umožňuje jednoduše integrovat ověření telefonních čísel do vaší webové aplikace. Widget se zobrazuje jako modální okno a podporuje více jazyků, přizpůsobení vzhledu a různé režimy ověření.

Začínáme

1. Základní integrace

Pro integraci widgetu do vaší stránky potřebujete pouze přidat skript a inicializovat widget:

<!-- Přidejte skript do vaší HTML stránky -->
<script src="https://verify-widget.smsmanager.com/modal.js"></script>

<script>
// Inicializujte widget
const modal = new PhoneValidationModal({
    siteKey: 'váš-site-klíč',
    onSuccess: function(data) {
        console.log('Telefonní číslo ověřeno:', data.phoneNumber);
    }
});

// Otevřete modální okno
modal.open();
</script>

2. Získání API klíče

API klíč obdržíte od vašeho správce systému nebo prostřednictvím Admin API. Každý tenant (zákazník) má svůj unikátní API klíč.

Konfigurace widgetu

Povinné parametry

siteKey (string)

• Popis: Unikátní identifikátor vašeho tenantu
• Povinné: Ano
• Příklad: '550e8400-e29b-41d4-a716-446655440000'

Volitelné parametry

language (string)

• Popis: Jazyk uživatelského rozhraní
• Výchozí: Automatická detekce z prohlížeče
• Dostupné jazyky:
  • 'en' - Angličtina
  • 'cs' - Čeština
  • 'sk' - Slovenština
  • 'pl' - Polština
• Příklad: language: 'cs'

defaultCountry (string)

• Popis: Předvolená země pro zadávání telefonního čísla
• Formát: ISO 3166-1 alpha-2 kód země
• Výhoda: Uživatelé mohou zadávat čísla bez mezinárodní předvolby
• Příklad: defaultCountry: 'CZ' (uživatel může zadat 777123456 místo +420777123456)

primaryColor (string)

• Popis: Hlavní barva widgetu (tlačítka, odkazy)
• Formát: HEX kód barvy
• Výchozí: '#3b82f6' (modrá)
• Příklad: primaryColor: '#e11d48'

verificationMode (string)

• Popis: Režim ověření kódu
• Možnosti:
  • 'online' (výchozí) - Ověření na serveru
  • 'offline' - Ověření lokálně ve vaší aplikaci
  • 'hybrid' - Kombinace obou režimů
• Příklad: verificationMode: 'offline'

onSuccess (function)

• Popis: Callback funkce volaná po úspěšném ověření
• Parametry: Objekt s daty o ověření
• Příklad:

onSuccess: function(data) {
    console.log('Ověřeno:', data.phoneNumber);
    console.log('Token:', data.token);
    console.log('Časová značka:', data.timestamp);
}

onError (function)

• Popis: Callback funkce volaná při chybě
• Parametry: Objekt s informacemi o chybě
• Příklad:

onError: function(error) {
    console.error('Chyba:', error.message);
}

onClose (function)

• Popis: Callback funkce volaná při zavření modálního okna
• Příklad:

onClose: function() {
    console.log('Modal zavřen');
}

debug (boolean)

• Popis: Zapne detailní logování do konzole
• Výchozí: false
• Příklad: debug: true

Metody widgetu

open()

Otevře modální okno s formulářem pro ověření.

modal.open();

close()

Zavře modální okno.

modal.close();

Příklady použití

Základní použití

const modal = new PhoneValidationModal({
    siteKey: 'váš-site-klíč',
    onSuccess: function(data) {
        // Zpracujte úspěšné ověření
        window.location.href = '/dashboard';
    },
    onError: function(error) {
        alert('Ověření selhalo: ' + error.message);
    }
});

// Otevřete modal při kliknutí na tlačítko
document.getElementById('verify-phone').addEventListener('click', function() {
    modal.open();
});

Pokročilá konfigurace

const modal = new PhoneValidationModal({
    siteKey: 'váš-site-klíč',
    language: 'cs',              // Vynutit češtinu
    defaultCountry: 'CZ',        // Předvolit Českou republiku
    primaryColor: '#15803d',     // Zelená barva
    verificationMode: 'online',  // Online ověření
    debug: true,                 // Zapnout debug logování
    onSuccess: function(data) {
        console.log('Úspěch!', data);
        // Uložit ověřené číslo
        saveVerifiedPhone(data.phoneNumber);
    },
    onError: function(error) {
        console.error('Chyba:', error);
        // Zobrazit chybovou hlášku
        showErrorMessage(error.message);
    },
    onClose: function() {
        console.log('Modal zavřen uživatelem');
    }
});

Offline ověření

Pro offline ověření musíte implementovat handler pro zprávy:

// Inicializace widgetu v offline režimu
const modal = new PhoneValidationModal({
    siteKey: 'váš-site-klíč',
    verificationMode: 'offline',
    onSuccess: function(data) {
        console.log('Ověřeno offline:', data);
    }
});

// Handler pro offline ověření
window.addEventListener('message', function(event) {
    // Ověřte původ zprávy
    if (event.origin !== 'https://verify-widget.smsmanager.com') return;
    
    if (event.data.type === 'validation:started') {
        // Uložte si důležité údaje pro ověření
        window.validationData = {
            phoneNumber: event.data.phoneNumber,
            token: event.data.token,
            timestamp: event.data.timestamp,
            proof: event.data.proof
        };
    }
    
    if (event.data.type === 'validation:code-entered') {
        // Ověřte kód na vašem backendu
        verifyCodeOnBackend(event.data.code, window.validationData)
            .then(isValid => {
                // Pošlete výsledek zpět do widgetu
                event.source.postMessage({
                    type: 'validation:offline-result',
                    success: isValid,
                    message: isValid ? 'Kód ověřen!' : 'Neplatný kód'
                }, event.origin);
            });
    }
});

Přizpůsobení vzhledu

Widget automaticky přizpůsobí své barvy podle parametru primaryColor. Ovlivněny jsou:

• Pozadí tlačítek
• Barva odkazů
• Aktivní stavy formulářových prvků
• Ikony úspěchu

Příklad s firemními barvami

const modal = new PhoneValidationModal({
    siteKey: 'váš-site-klíč',
    primaryColor: '#dc2626',  // Červená firemní barva
    language: 'cs'
});

Jazykové mutace

Widget automaticky detekuje jazyk prohlížeče, ale můžete ho vynutit:

// Pro české uživatele
const modalCS = new PhoneValidationModal({
    siteKey: 'váš-site-klíč',
    language: 'cs'
});

// Pro slovenské uživatele
const modalSK = new PhoneValidationModal({
    siteKey: 'váš-site-klíč',
    language: 'sk'
});

Řešení problémů

Widget se neotevírá

1. Zkontrolujte, zda je skript správně načten
2. Ověřte platnost API klíče
3. Zkontrolujte konzoli prohlížeče pro chybové hlášky

Chyba "Invalid tenant"

• API klíč je neplatný nebo neexistuje
• Kontaktujte správce pro získání správného klíče

Chyba "Rate limit exceeded"

• Překročen limit požadavků
• Počkejte uvedenou dobu před dalším pokusem

Modal se nezavírá

• Zkontrolujte JavaScript chyby v konzoli
• Ujistěte se, že neblokujete výchozí chování

Bezpečnostní doporučení

1. Nikdy nevkládejte API klíč přímo do kódu, použijte konfigurační soubor
2. Implementujte proper error handling
3. Pro produkční prostředí používejte pouze HTTPS
4. Ověřujte původ zpráv při offline režimu
5. Pravidelně aktualizujte widget na nejnovější verzi

Podpora

Pokud narazíte na problémy:

1. Zkontrolujte tuto dokumentaci
2. Zapněte debug režim pro více informací
3. Kontaktujte technickou podporu s detailním popisem problému