Instalace a inicializace

Přidání knihovny do projektu

Knihovna je distribuována jako AAR artefakt společně s POM souborem závislostí. Tyto soubory jsou merchantům poskytovány na vyžádání.

Doporučený postup integrace:

1. Umístěte předaný AAR soubor do projektu (typicky do složky app/libs).
2. Přidejte AAR jako závislost aplikace.
3. Zajistěte dostupnost závislostí uvedených v předaném POM souboru.

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

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

Informace

POM soubor dodaný spolu s AAR obsahuje deklarované závislosti knihovny. Při integraci vždy vycházejte z těchto dodaných artefaktů (AAR + POM).

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.
email	String	✅	E-mailová adresa zákazníka.
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.
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",
            email = "zakaznik@example.com",
            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 použít initialize(callback) ručně:

val session = ComgateSecureSession(
    checkoutId = "váš-checkout-id",
    email = "zakaznik@example.com",
    context = applicationContext,
    threeDSConfig = ThreeDSConfig(),
    lifecycleOwner = this
)

session.initialize { result ->
    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:

// Composable reagující na stav session
when (session.sessionState) {
    SessionState.NotInitialized -> {
        Button(onClick = { 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 = { 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.InitNetworkError	INIT_NETWORK_ERROR	Síťová chyba při stahování konfigurace.
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ě.

Tip

Pokud initialize() zavoláte znovu, zatímco session je ve stavu Initializing, callback okamžitě obdrží chybu ComgateError.InitFailed. Počkejte na přechod do stavu Ready nebo Failed, než inicializaci opakujete.

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
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.
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á.
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(
    panHint = "Číslo karty",
    expiryHint = "MM/RR",
    cvvHint = "CVV",
    panInvalidError = "Neplatné číslo karty",
    expiryInvalidMonthError = "Neplatný měsíc",
    expiryExpiredError = "Karta je expirovaná",
    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",
    email = "zakaznik@example.com",
    context = applicationContext,
    threeDSConfig = ThreeDSConfig(),
    translation = translation,
    lifecycleOwner = this
)

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

val session = ComgateSecureSession(
    checkoutId = "váš-checkout-id",
    email = "zakaznik@example.com",
    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.