Instalace a inicializace

Ke stažení

Knihovna je distribuována jako AAR artefakt společně s POM souborem závislostí. Stáhněte si verzi, kterou chcete integrovat:

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

Přidání knihovny do projektu

Doporučený postup integrace:

Umístěte stažený AAR soubor do projektu (typicky do složky app/libs).
Přidejte AAR jako závislost aplikace.
Zajistěte dostupnost závislostí uvedených v POM souboru.

Příklad základního přidání AAR v build.gradle.kts:

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

Informace

POM soubor ke stažení obsahuje deklarované závislosti knihovny. Při integraci vždy vycházejte z dvojice AAR + POM stejné verze.

Upozornění

Knihovna vyžaduje compileSdk 34 a minSdk 28. Ověřte, že konfigurace vaší aplikace splňuje tyto požadavky.

Konfigurace AndroidManifest.xml

Knihovna 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 knihovny automaticky registrován meta-data záznam:

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

Vytvoření session

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

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

Parametry konstruktoru

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

Informace

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

Inicializace

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

Android context se předává přímo do konstruktoru, kde je interně uložen (application context). Samostatné volání initializeContext(...) již 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(),  // výchozí 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 Karetní data
                }
            }
        }
    }

}

Informace

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

Ruční inicializace (alternativa)

Pokud potřebujete inicializaci spustit později, lze volat initialize() ručně. Preferovaný způsob je suspendovatelná funkce volaná z coroutine:

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

// Doporučené — 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ždém okamžiku 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 byla právě vytvořena nebo byl zavolán `cleanup()` (lifecycle destroy). `initialize()` zatím nebyla volána.
`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 při inicializaci

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

Chyba	Kód	Popis
`ComgateError.DeviceRooted`	`DEVICE_ROOTED`	Zařízení je pravděpodobně rootované nebo jinak pozměněné. Inicializace je zablokovaná za účelem ochrany karetních dat. V `devMode` se tato kontrola přeskočí.
`ComgateError.InitNetworkError`	`INIT_NETWORK_ERROR`	Síťová chyba při stahování konfigurace.
`ComgateError.InitUnauthorized`	`INIT_UNAUTHORIZED`	Server vrátil HTTP 401 při inicializaci — neplatná nebo expirovaná autorizace.
`ComgateError.InitFailed`	`INIT_FAILED`	Inicializace selhala z jiného důvodu (např. neplatná odpověď serveru).
`ComgateError.ApplicationNotAllowed`	`APPLICATION_NOT_ALLOWED`	Package name aplikace není na seznamu povolených aplikací.

Informace

Callback předaný do initialize() (nebo 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 nebo vlastní instanci Translation
Uživatelsky nastavitelné jsou pouze tyto klíče:

Klíč	Popis
`panLabel`	Label nad polem pro číslo karty (PAN).
`expiryLabel`	Label nad polem pro datum platnosti.
`cvvLabel`	Label nad polem pro CVV kód.
`fullNameLabel`	Label nad polem pro jméno držitele karty.
`panHint`	Placeholder text v poli pro číslo karty (PAN).
`expiryHint`	Placeholder text v poli pro datum platnosti (např. `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 polem při zadání neplatného čísla karty.
`expiryInvalidMonthError`	Chybová zpráva zobrazená pod polem expirace při zadání neplatného měsíce (např. `13`).
`expiryExpiredError`	Chybová zpráva zobrazená pod polem expirace, když je karta prošlá.
`fullNameRequiredError`	Chybová zpráva zobrazená pod polem jména, pokud není vyplněno.
`payButtonText`	Text platebního tlačítka v klidovém (aktivním) stavu.
`payButtonProcessingText`	Text platebního tlačítka během zpracování platby.
`statusPaid`	Zpráva zobrazená v `SecurePaymentStatusView` při úspěšné platbě.
`statusPending`	Zpráva zobrazená v `SecurePaymentStatusView`, když platba čeká na finální stav.
`loadingProcessingText`	Text zobrazený v `SecureLoadingView` (překryvná vrstva) během zpracování platby.
`threeDSCancelButton`	Text tlačítka 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
)

Při použití rozdělených polí (SecurePanField, SecureExpiryField, SecureCvvField) se texty aplikují přes session a použité komponenty knihovny.

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

Kódy podporovaných jazyků

ComgateSecureSession.supportedLanguageCodes vrací abecedně seřazený seznam BCP 47 / ISO 639-1 kódů jazyků, pro které knihovna obsahuje vestavěný překlad. Tento seznam lze využít k naplnění výběru jazyka v UI nebo ke zjištění, zda je jazyk zařízení podporován.

Aktuálně 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

Příklad — automatická detekce jazyka zařízení s fallbackem 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
)

Příklad — naplnění výběru jazyka v UI a propojení s překladem:

// Získání seznamu podporovaných kódů
val languageCodes = ComgateSecureSession.supportedLanguageCodes

// Po výběru jazyka uživatelem
val selectedCode = "sk"
val translation = Translation.forLanguageCode(selectedCode)

Ke stažení​

Přidání knihovny do projektu​

Konfigurace AndroidManifest.xml​

Vytvoření session​

Parametry konstruktoru​

Inicializace​

Ruční inicializace (alternativa)​

Stav session (SessionState)​

Stavy​

Typický životní cyklus​

Vlastnosti session​

Použití v UI (Compose)​

Chyby při inicializaci​

Překlady (lokalizace)​

Aktuálně dostupné překlady​

Kódy podporovaných jazyků​

Ke stažení

Přidání knihovny do projektu

Konfigurace AndroidManifest.xml

Vytvoření session

Parametry konstruktoru

Inicializace

Ruční inicializace (alternativa)

Stav session (SessionState)

Stavy

Typický životní cyklus

Vlastnosti session

Použití v UI (Compose)

Chyby při inicializaci

Překlady (lokalizace)

Aktuálně dostupné překlady

Kódy podporovaných jazyků