Inštalácia a inicializácia

Na stiahnutie

Knižnica je distribuovaná ako AAR artefakt spolu s POM súborom závislostí. Stiahnite si verziu, ktorú chcete integrovať:

Verzia	AAR	POM
1.0.0	comgateSdk-1.0.0.aar	comgateSdk-1.0.0.pom

Pridanie knižnice do projektu

Odporúčaný postup integrácie:

Umiestnite stiahnutý AAR súbor do projektu (typicky do zložky app/libs).
Pridajte AAR ako závislosť aplikácie.
Zabezpečte dostupnosť závislostí uvedených v POM súbore.

Príklad základného pridania AAR v build.gradle.kts:

dependencies {
    implementation(files("libs/comgateSdk-1.0.0.aar"))
}

Informácie

POM súbor na stiahnutie obsahuje deklarované závislosti knižnice. Pri integrácii vždy vychádzajte z dvojice AAR + POM rovnakej verzie.

Upozornenie

Knižnica vyžaduje compileSdk 34 a minSdk 28. Ověřte, že konfigurace vašej aplikace splňuje tieto požadavky.

Konfigurace AndroidManifest.xml

Knižnica ve svém manifestu automaticky deklaruje potřebná oprávnění a komponenty. Ujistěte se, že vaše aplikace má povolení pro přístup k internetu:

<uses-permission android:name="android.permission.INTERNET" />

Pro využití Google Pay je v manifestu knižnice automaticky registrován meta-data záznam:

<meta-data
    android:name="com.google.android.gms.wallet.api.enabled"
    android:value="true" />

Vytvorenie session

Třída ComgateSecureSession je hlavním vstupním bodem pro práci s knihovnou. Session zabezpečuje:

interní bezpečnostní inicializaci,
inicializaci 3D Secure,
spracovania karetních plateb a Google Pay plateb.

Parametry konstruktoru

Parametr	Typ	Povinný	Popis
`checkoutId`	`String`	✅	Identifikátor Checkout SDK propojení. Získáte v klientskom portáli Comgate.
`context`	`Context`	✅	Android kontext aplikace (typicky `applicationContext`).
`threeDSConfig`	`ThreeDSConfig`	✅	Konfigurace 3D Secure (UI, timeout, verze protokolu). Podrobnosti v sekcii Kartové údaje - 3D Secure.
`lifecycleOwner`	`LifecycleOwner`	✅	Vlastník životního cyklu (napr. `Activity`/`Fragment`). Session se zaregistruje jako observer a pri `onDestroy()` automaticky uvolní zdroje.
`devMode`	`Boolean`		Zapíná vývojový/testovací režim (napr. dev SSL). Ovlivňuje také prostředí Google Pay — `true` přepne na testovací prostředí (`TEST`), `false` na produkční (`PRODUCTION`). Predvolené `false`.
`googleMerchantId`	`String?`		Google Pay Merchant ID. Povinný pro Google Pay v produkci.
`googleMerchantName`	`String?`		Názov obchodníka zobrazený v Google Pay platebním dialogu.
`translation`	`Translation`		Překlady textů komponent. Predvolené `Translation.English`.
`lang`	`String?`		Kód jazyka (BCP 47 / ISO 639-1) odesílaný s platebním požadavkem (napr. `"cs"`, `"en"`). Pokud nie je zadaný, použije sa jazyk zariadeania (je-li podporován). Dostupné kódy viz `ComgateSecureSession.supportedLanguageCodes`.
`onInitialized`	`((Result<Unit>) -> Unit)?`		Volitelný callback pro automatickou inicializaci session z konstruktoru.

Informácie

Síťová infrastruktura a komunikace jsou interně řízené knihovnou. Pri standardní integraci není potřeba nic měnit.

Inicializace

Doporučený způsob inicializace je předat callback onInitialized priamo do konstruktoru ComgateSecureSession.

Android context se odovzdáva priamo do konstruktoru, kde je interně uložen (application context). Samostatné volání initializeContext(...) už není potřeba.

class MainActivity : AppCompatActivity() {

    private lateinit var session: ComgateSecureSession

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        session = ComgateSecureSession(
            checkoutId = "váš-checkout-id",
            context = applicationContext,
            threeDSConfig = ThreeDSConfig(),  // predvolené 3DS konfigurace
            lifecycleOwner = this,
            onInitialized = { result ->
                result.onSuccess {
                    // Session je připravena - lze zpracovávat platby
                }.onFailure { e ->
                    // Chyba inicializace
                    Log.e("Payment", "Init failed: ${e.message}")
                }
            }
        )

        setContent {
            MaterialTheme {
                Surface(modifier = Modifier.fillMaxSize()) {
                    // Váš platební formulář — viz sekce Kartové údaje
                }
            }
        }
    }

}

Informácie

Callback onInitialized (i callback metody initialize) je volán na hlavním vlákně (main thread). Můžete v něm priamo aktualizovat UI.

Ruční inicializace (alternativa)

Ak potřebujete inicializaci spustit později, lze volať initialize() ručně. Preferovaný spôsob je suspendovaná funkcia volaná z coroutine:

val session = ComgateSecureSession(
    checkoutId = "váš-checkout-id",
    context = applicationContext,
    threeDSConfig = ThreeDSConfig(),
    lifecycleOwner = this
)

// Odporúčané — suspend fun volaná z coroutine
lifecycleScope.launch {
    val result = session.initialize()
    result.onSuccess {
        // Session je připravena
    }.onFailure { e ->
        // Chyba inicializace
    }
}

Stav session (SessionState)

ComgateSecureSession vystavuje property sessionState typu SessionState, která v každom okamihu popisuje aktuální fázi životního cyklu session. Pro jednoduché kontroly (true/false) je k dispozici také zkratka isInitialized.

Stavy

Stav	Kdy platí
`SessionState.NotInitialized`	Session bola právě vytvořena alebo byl zavolán `cleanup()` (lifecycle destroy). `initialize()` zatím nebola volaná.
`SessionState.Initializing`	`initialize()` právě probíhá — probíhá síťová komunikace a inicializace 3DS SDK.
`SessionState.Ready`	Inicializace úspěšně dokončena. Session je připravena zpracovávat platby.
`SessionState.Failed(error)`	Inicializace selhala. Property `error` (typ `ComgateError`) nese konkrétní příčinu. Session lze znovu inicializovat voláním `initialize()`.

Typický životný cyklus

NotInitialized → Initializing → Ready
                             ↘ Failed → Initializing → Ready   (opakovaný pokus)
Ready → NotInitialized                                         (lifecycle destroy)

Vlastnosti session

Vlastnost	Typ	Popis
`sessionState`	`SessionState`	Aktuální stav session (viz tabulka výše).
`isInitialized`	`Boolean`	Zkratka: `true` právě tehdy, když `sessionState == SessionState.Ready`.

Použití v UI (Compose)

Přečtením session.sessionState lze granulárně reagovat na každý stav a zobrazovat příslušný UI prvek:

val scope = rememberCoroutineScope()

// Composable reagující na stav session
when (session.sessionState) {
    SessionState.NotInitialized -> {
        Button(onClick = { scope.launch { session.initialize() } }) {
            Text("Inicializovat")
        }
    }
    SessionState.Initializing -> {
        CircularProgressIndicator()
    }
    SessionState.Ready -> {
        // Platební formulář je připraven
        PaymentForm(session = session)
    }
    is SessionState.Failed -> {
        val error = (session.sessionState as SessionState.Failed).error
        Text("Chyba inicializace: ${error.message}")
        Button(onClick = { scope.launch { session.initialize() } }) {
            Text("Zkusit znovu")
        }
    }
}

Chyby pri inicializaci

Stav SessionState.Failed nese ComgateError s popisem příčiny. Nejčastější chyby pri inicializaci:

Chyba	Kód	Popis
`ComgateError.DeviceRooted`	`DEVICE_ROOTED`	Zariadenie je pravdepodobne rootované alebo inak pozmenĕné. Inicializácia je zablokovaná za účelom ochrany kartových dát. V `devMode` sa táto kontrola preskočí.
`ComgateError.InitNetworkError`	`INIT_NETWORK_ERROR`	Síťová chyba pri stahování konfigurace.
`ComgateError.InitUnauthorized`	`INIT_UNAUTHORIZED`	Server vrátil HTTP 401 pri inicializaci — neplatná alebo expirovaná autorizácia.
`ComgateError.InitFailed`	`INIT_FAILED`	Inicializace selhala z jiného dôvodu (napr. neplatná odpověď serveru).
`ComgateError.ApplicationNotAllowed`	`APPLICATION_NOT_ALLOWED`	Package name aplikace není na seznamu povolených aplikací.

Informácie

Callback odovzdaný do initialize() (alebo onInitialized) a přechod stavu na Ready/Failed jsou vždy doručeny na hlavním vlákně. sessionState lze bezpečně číst z jakéhokoli vlákna (property je označena jako @Volatile), ale UI aktualizace provádějte vždy na hlavním vlákně.

Překlady (lokalizace)

Texty komponent lze lokalizovat pomocí Translation.

Překlady se předávají do ComgateSecureSession parametrem translation
Lze použít vestavěný preset alebo vlastní instanci Translation
Uživatelsky nastavitelné jsou iba tieto klíče:

Klíč	Popis
`panLabel`	Label nad poľom pro číslo karty (PAN).
`expiryLabel`	Label nad poľom pro datum platnosti.
`cvvLabel`	Label nad poľom pro CVV kód.
`fullNameLabel`	Label nad poľom pro jméno držitele karty.
`panHint`	Placeholder text v poli pro číslo karty (PAN).
`expiryHint`	Placeholder text v poli pro datum platnosti (napr. `MM/RR`).
`cvvHint`	Placeholder text v poli pro CVV kód.
`fullNameHint`	Placeholder text v poli pro jméno držitele karty.
`panInvalidError`	Chybová zpráva zobrazená pod PAN poľom pri zadání neplatného čísla karty.
`expiryInvalidMonthError`	Chybová zpráva zobrazená pod poľom expirace pri zadání neplatného měsíce (napr. `13`).
`expiryExpiredError`	Chybová zpráva zobrazená pod poľom expirace, když je karta prošlá.
`fullNameRequiredError`	Chybová zpráva zobrazená pod poľom jména, ak není vyplněno.
`payButtonText`	Text platebního tlačidla v klidovém (aktivním) stavu.
`payButtonProcessingText`	Text platebního tlačidla počas spracovania platby.
`statusPaid`	Zpráva zobrazená v `SecurePaymentStatusView` pri úspěšné platbě.
`statusPending`	Zpráva zobrazená v `SecurePaymentStatusView`, když platba čeká na finální stav.
`loadingProcessingText`	Text zobrazený v `SecureLoadingView` (překryvná vrstva) počas spracovania platby.
`threeDSCancelButton`	Text tlačidla pro zrušení v dialogu 3D Secure ověření.

Aktuálně dostupné překlady

Překlad	Hodnota
Angličtina	`Translation.English`
Bulharština	`Translation.Bulgarian`
Čeština	`Translation.Czech`
Dánština	`Translation.Danish`
Estonština	`Translation.Estonian`
Finština	`Translation.Finnish`
Francouzština	`Translation.French`
Chorvatština	`Translation.Croatian`
Italština	`Translation.Italian`
Litevština	`Translation.Lithuanian`
Lotyšština	`Translation.Latvian`
Maďarština	`Translation.Hungarian`
Němčina	`Translation.German`
Nizozemština	`Translation.Dutch`
Norština	`Translation.Norwegian`
Polština	`Translation.Polish`
Portugalština	`Translation.Portuguese`
Rumunština	`Translation.Romanian`
Ruština	`Translation.Russian`
Řečtina	`Translation.Greek`
Slovenština	`Translation.Slovak`
Slovinština	`Translation.Slovenian`
Španělština	`Translation.Spanish`
Švédština	`Translation.Swedish`
Ukrajinština	`Translation.Ukrainian`
Vietnamština	`Translation.Vietnamese`

val translation = Translation(
    panLabel = "Číslo karty",
    expiryLabel = "Platnost",
    cvvLabel = "CVC/CVV",
    fullNameLabel = "Jméno držitele",
    panHint = "Číslo karty",
    expiryHint = "MM/RR",
    cvvHint = "CVV",
    fullNameHint = "Jméno a příjmení",
    panInvalidError = "Neplatné číslo karty",
    expiryInvalidMonthError = "Neplatný měsíc",
    expiryExpiredError = "Karta je expirovaná",
    fullNameRequiredError = "Vyplňte jméno držitele",
    payButtonText = "Zaplatit",
    payButtonProcessingText = "Zpracovávám...",
    statusPaid = "Zaplaceno",
    statusPending = "Zpracovává se",
    loadingProcessingText = "Zpracovávám platbu…",
    threeDSCancelButton = "Zrušit"
)

val session = ComgateSecureSession(
    checkoutId = "váš-checkout-id",
    context = applicationContext,
    threeDSConfig = ThreeDSConfig(),
    translation = translation,
    lifecycleOwner = this
)

Příklad s vestavěným překladem:

val session = ComgateSecureSession(
    checkoutId = "váš-checkout-id",
    context = applicationContext,
    threeDSConfig = ThreeDSConfig(),
    translation = Translation.Czech,
    lifecycleOwner = this
)

Pri použitie rozdělených polí (SecurePanField, SecureExpiryField, SecureCvvField) se texty aplikují přes session a použité komponenty knižnice.

Pro jednotlivá pole lze překlady labelů dále přepsat lokálně přes labelText. Ak nechcete label zobrazit vůbec, nastavte showLabel = false (v Compose) alebo app:secureFieldShowLabel="false" (v XML).

Kódy podporovaných jazykov

ComgateSecureSession.supportedLanguageCodes vracía abecedně užívaný zoznam BCP 47 / ISO 639-1 kódov jazykov, pre ktoré knižnica obsahuje vestavený preklad. Tento zoznam možno využiť na naplnenie výberu jazyka v UI alebo na zistení, či je jazyk zariadenia podporovaný.

Aktuálne dostupné kódy: bg, cs, da, de, el, en, es, et, fi, fr, hr, hu, it, lt, lv, nl, no, pl, pt, ro, ru, sk, sl, sv, uk, vi

Príklad — automatická detekcia jazyka zariadenia s fallbackom na angličtinu:

val deviceLang = Locale.getDefault().language.lowercase()
val resolvedLang = deviceLang
    .takeIf { it in ComgateSecureSession.supportedLanguageCodes }
    ?: "en"

val session = ComgateSecureSession(
    checkoutId = "váš-checkout-id",
    context = applicationContext,
    threeDSConfig = ThreeDSConfig(),
    translation = Translation.forLanguageCode(resolvedLang),
    lang = resolvedLang,
    lifecycleOwner = this
)

Príklad — naplnenie výberu jazyka v UI a prepojenie s prekladom:

// Získanie zoznamu podporovaných kódov
val languageCodes = ComgateSecureSession.supportedLanguageCodes

// Po výbere jazyka užívateľom
val selectedCode = "sk"
val translation = Translation.forLanguageCode(selectedCode)

Na stiahnutie​

Pridanie knižnice do projektu​

Konfigurace AndroidManifest.xml​

Vytvorenie session​

Parametry konstruktoru​

Inicializace​

Ruční inicializace (alternativa)​

Stav session (SessionState)​

Stavy​

Typický životný cyklus​

Vlastnosti session​

Použití v UI (Compose)​

Chyby pri inicializaci​

Překlady (lokalizace)​

Aktuálně dostupné překlady​

Kódy podporovaných jazykov​

Na stiahnutie

Pridanie knižnice do projektu

Konfigurace AndroidManifest.xml

Vytvorenie session

Parametry konstruktoru

Inicializace

Ruční inicializace (alternativa)

Stav session (SessionState)

Stavy

Typický životný cyklus

Vlastnosti session

Použití v UI (Compose)

Chyby pri inicializaci

Překlady (lokalizace)

Aktuálně dostupné překlady

Kódy podporovaných jazykov