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. Overte, že konfigurácia vašej aplikácie spĺňa tieto požiadavky.

Konfigurácia AndroidManifest.xml

Knižnica vo svojom manifeste automaticky deklaruje potrebné oprávnenia a komponenty. Uistite sa, že vaša aplikácia má povolenie na prístup k internetu:

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

Pre využitie Google Pay je v manifeste knižnice automaticky registrovaný meta-data záznam:

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

Vytvorenie session

Trieda ComgateSecureSession je hlavným vstupným bodom pre prácu s knižnicou. Session zabezpečuje:

internú bezpečnostnú inicializáciu,
inicializáciu 3D Secure,
spracovania karetních plateb a Google Pay plateb.

Parametre konštruktora

Parameter	Typ	Povinný	Popis
`checkoutId`	`String`	✅	Identifikátor Checkout SDK propojení. Získáte v klientskom portáli Comgate.
`context`	`Context`	✅	Android kontext aplikácie (typicky `applicationContext`).
`threeDSConfig`	`ThreeDSConfig`	✅	Konfigurácia 3D Secure (UI, timeout, verzia protokolu). Podrobnosti v sekcii 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ína vývojový/testovací režim (napr. dev SSL). Ovplyvňuje aj prostredie Google Pay — `true` prepne na testovacie prostredie (`TEST`), `false` na produkčné (`PRODUCTION`). Predvolené `false`.
`googleMerchantId`	`String?`		Google Pay Merchant ID. Povinný pre Google Pay v produkcii.
`googleMerchantName`	`String?`		Názov obchodníka zobrazený v Google Pay platebním dialogu.
`translation`	`Translation`		Preklady textov komponentov. 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)?`		Voliteľný callback pre automatickú inicializáciu session z konštruktora.

Informácie

Sieťová infraštruktúra a komunikácia sú interne riadené knižnicou. Pri štandardnej integrácii nie je potrebné nič meniť.

Inicializácia

Odporúčaný spôsob inicializácie je odovzdať callback onInitialized priamo do konštruktora ComgateSecureSession.

Android context sa odovzdáva priamo do konštruktora, kde je interne uložený (application context). Samostatné volanie initializeContext(...) už nie je potrebné.

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 pripravená - možno spracovávať platby
                }.onFailure { e ->
                    // Chyba inicializace
                    Log.e("Payment", "Init failed: ${e.message}")
                }
            }
        )

        setContent {
            MaterialTheme {
                Surface(modifier = Modifier.fillMaxSize()) {
                    // Váš platobný formulár — viď sekcia Kartové údaje
                }
            }
        }
    }

}

Informácie

Callback onInitialized (aj callback metódy initialize) je volaný na hlavnom vlákne (main thread). Môžete v ňom priamo aktualizovať UI.

Ručná inicializácia (alternatíva)

Ak potrebujete inicializáciu spustiť neskôr, možno volať initialize() ručne. 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 pripravená
    }.onFailure { e ->
        // Chyba inicializace
    }
}

Stav session (SessionState)

ComgateSecureSession vystavuje property sessionState typu SessionState, ktorá v každom okamihu popisuje aktuálnu fázu životného cyklu session. Pre jednoduché kontroly (true/false) je k dispozícii aj skratka isInitialized.

Stavy

Stav	Kedy platí
`SessionState.NotInitialized`	Session bola práve vytvorená alebo bol zavolaný `cleanup()` (lifecycle destroy). `initialize()` zatiaľ nebola volaná.
`SessionState.Initializing`	`initialize()` práve prebieha — prebieha sieťová komunikácia a inicializácia 3DS SDK.
`SessionState.Ready`	Inicializácia úspešne dokončená. Session je pripravená spracovávať platby.
`SessionState.Failed(error)`	Inicializácia zlyhala. Property `error` (typ `ComgateError`) nesie konkrétnu príčinu. Session možno znova inicializovať volaním `initialize()`.

Typický životný cyklus

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

Vlastnosti session

Vlastnosť	Typ	Popis
`sessionState`	`SessionState`	Aktuálny stav session (viď tabuľka vyššie).
`isInitialized`	`Boolean`	Skratka: `true` práve vtedy, keď `sessionState == SessionState.Ready`.

Použitie v UI (Compose)

Prečítaním session.sessionState možno granulárne reagovať na každý stav a zobrazovať príslušný UI prvok:

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 -> {
        // Platobný formulár je pripravený
        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 nesie ComgateError s popisom príčiny. Najčastejšie chyby pri inicializácii:

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`	Sieťová chyba pri sťahovaní konfigurácie.
`ComgateError.InitUnauthorized`	`INIT_UNAUTHORIZED`	Server vrátil HTTP 401 pri inicializaci — neplatná alebo expirovaná autorizácia.
`ComgateError.InitFailed`	`INIT_FAILED`	Inicializácia zlyhala z iného dôvodu (napr. neplatná odpoveď servera).
`ComgateError.ApplicationNotAllowed`	`APPLICATION_NOT_ALLOWED`	Package name aplikácie nie je na zozname povolených aplikácií.

Informácie

Callback odovzdaný do initialize() (alebo onInitialized) a prechod stavu na Ready/Failed sú vždy doručené na hlavnom vlákne. sessionState možno bezpečne čítať z akéhokoľvek vlákna (property je označená ako @Volatile), ale UI aktualizácie vykonávajte vždy na hlavnom vlákne.

Preklady (lokalizácia)

Texty komponentov možno lokalizovať pomocou Translation.

Preklady sa odovzdávajú do ComgateSecureSession parametrom translation
Možno použiť vstavaný preset alebo vlastnú inštanciu Translation
Používateľsky nastaviteľné sú iba tieto kľúče:

Kľúč	Popis
`panLabel`	Label nad poľom pre číslo karty (PAN).
`expiryLabel`	Label nad poľom pre dátum platnosti.
`cvvLabel`	Label nad poľom pre CVV kód.
`fullNameLabel`	Label nad poľom pre meno držiteľa karty.
`panHint`	Placeholder text v poli pre číslo karty (PAN).
`expiryHint`	Placeholder text v poli pre dátum platnosti (napr. `MM/RR`).
`cvvHint`	Placeholder text v poli pre CVV kód.
`fullNameHint`	Placeholder text v poli pre meno držiteľa karty.
`panInvalidError`	Chybová zpráva zobrazená pod PAN poľom pri zadání neplatného čísla karty.
`expiryInvalidMonthError`	Chybová správa zobrazená pod poľom expirácie pri zadaní neplatného mesiaca (napr. `13`).
`expiryExpiredError`	Chybová zpráva zobrazená pod poľom expirace, když je karta prošlá.
`fullNameRequiredError`	Chybová správa zobrazená pod poľom mena, ak nie je vyplnené.
`payButtonText`	Text platebního tlačidla v klidovém (aktivním) stavu.
`payButtonProcessingText`	Text platebního tlačidla počas spracovania platby.
`statusPaid`	Správa zobrazená v `SecurePaymentStatusView` pri úspešnej platbe.
`statusPending`	Správa zobrazená v `SecurePaymentStatusView`, keď platba čaká na finálny stav.
`loadingProcessingText`	Text zobrazený v `SecureLoadingView` (prekryvná vrstva) počas spracovania platby.
`threeDSCancelButton`	Text tlačidla na zrušenie v dialógu 3D Secure overenia.

Aktuálne dostupné preklady

Preklad	Hodnota
Angličtina	`Translation.English`
Bulharčina	`Translation.Bulgarian`
Čeština	`Translation.Czech`
Dánčina	`Translation.Danish`
Estónčina	`Translation.Estonian`
Fínčina	`Translation.Finnish`
Francúzština	`Translation.French`
Chorvátčina	`Translation.Croatian`
Taliančina	`Translation.Italian`
Litovčina	`Translation.Lithuanian`
Lotyština	`Translation.Latvian`
Maďarčina	`Translation.Hungarian`
Nemčina	`Translation.German`
Holandčina	`Translation.Dutch`
Nórčina	`Translation.Norwegian`
Poľština	`Translation.Polish`
Portugalčina	`Translation.Portuguese`
Rumunčina	`Translation.Romanian`
Ruština	`Translation.Russian`
Gréčtina	`Translation.Greek`
Slovenčina	`Translation.Slovak`
Slovinčina	`Translation.Slovenian`
Španielčina	`Translation.Spanish`
Švédčina	`Translation.Swedish`
Ukrajinčina	`Translation.Ukrainian`
Vietnamčina	`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
)

Príklad so vstavaným prekladom:

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

Pri použití rozdelených polí (SecurePanField, SecureExpiryField, SecureCvvField) sa texty aplikujú cez session a použité komponenty knižnice.

Pre jednotlivé polia možno preklady labelov ďalej prepísať lokálne cez labelText. Ak nechcete label zobraziť vôbec, nastavte showLabel = false (v Compose) alebo app:secureFieldShowLabel="false" (v XML).

Kódy podporovaných jazykov

ComgateSecureSession.supportedLanguageCodes vracia abecedne zoradený zoznam BCP 47 / ISO 639-1 kódov jazykov, pre ktoré knižnica obsahuje vstavaný preklad. Tento zoznam možno využiť na naplnenie výberu jazyka v UI alebo na zistenie, č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​

Konfigurácia AndroidManifest.xml​

Vytvorenie session​

Parametre konštruktora​

Inicializácia​

Ručná inicializácia (alternatíva)​

Stav session (SessionState)​

Stavy​

Typický životný cyklus​

Vlastnosti session​

Použitie v UI (Compose)​

Chyby pri inicializaci​

Preklady (lokalizácia)​

Aktuálne dostupné preklady​

Kódy podporovaných jazykov​

Na stiahnutie

Pridanie knižnice do projektu

Konfigurácia AndroidManifest.xml

Vytvorenie session

Parametre konštruktora

Inicializácia

Ručná inicializácia (alternatíva)

Stav session (SessionState)

Stavy

Typický životný cyklus

Vlastnosti session

Použitie v UI (Compose)

Chyby pri inicializaci

Preklady (lokalizácia)

Aktuálne dostupné preklady

Kódy podporovaných jazykov