Skip to main content

Inštalácia a inicializácia

Přidání knižnice do projektu​

Knižnica je distribuována jako AAR artefakt spolu s POM súborom závislostí. Tieto súbory jsou merchantům poskytovány na vyžádání.

Doporučený postup integrace:

  1. Umiestnite odovzdaný AAR súbor do projektu (typicky do zložky app/libs).
  2. Přidejte AAR jako závislost aplikace.
  3. Zabezpečte dostupnost závislostí uvedených v odovzdanom POM súboru.

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

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

POM súbor dodaný spolu s AAR obsahuje deklarované závislosti knižnice. Pri integraci vždy vychádzajte z těchto dodaných artefaktů (AAR + POM).

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​

ParametrTypPovinnýPopis
checkoutIdString✅Identifikátor Checkout SDK propojení. Získáte v klientskom portáli Comgate.
emailString✅E-mailová adresa zákazníka.
contextContext✅Android kontext aplikace (typicky applicationContext).
threeDSConfigThreeDSConfig✅Konfigurace 3D Secure (UI, timeout, verze protokolu). Podrobnosti v sekcii Kartové údaje - 3D Secure.
lifecycleOwnerLifecycleOwner✅Vlastník životního cyklu (napr. Activity/Fragment). Session se zaregistruje jako observer a pri onDestroy() automaticky uvolní zdroje.
devModeBooleanZapí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.
googleMerchantIdString?Google Pay Merchant ID. Povinný pro Google Pay v produkci.
googleMerchantNameString?Názov obchodníka zobrazený v Google Pay platebním dialogu.
translationTranslationPřeklady textů komponent. Predvolené Translation.English.
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",
            email = "zakaznik@example.com",
            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",
    email = "zakaznik@example.com",
    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​

StavKdy platí
SessionState.NotInitializedSession bola právě vytvořena alebo byl zavolán cleanup() (lifecycle destroy). initialize() zatím nebola volaná.
SessionState.Initializinginitialize() právě probíhá — probíhá síťová komunikace a inicializace 3DS SDK.
SessionState.ReadyInicializace ú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​

VlastnostTypPopis
sessionStateSessionStateAktuální stav session (viz tabulka výše).
isInitializedBooleanZkratka: 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:

ChybaKódPopis
ComgateError.DeviceRootedDEVICE_ROOTEDZariadenie 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.InitNetworkErrorINIT_NETWORK_ERRORSíťová chyba pri stahování konfigurace.
ComgateError.InitFailedINIT_FAILEDInicializace selhala z jiného dôvodu (napr. neplatná odpověď serveru).
ComgateError.ApplicationNotAllowedAPPLICATION_NOT_ALLOWEDPackage 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ě.

Tip

Ak 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 alebo 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 alebo vlastní instanci Translation
  • Uživatelsky nastavitelné jsou iba tieto klíče:
KlíčPopis
panLabelLabel nad poľom pro číslo karty (PAN).
expiryLabelLabel nad poľom pro datum platnosti.
cvvLabelLabel nad poľom pro CVV kód.
fullNameLabelLabel nad poľom pro jméno držitele karty.
panHintPlaceholder text v poli pro číslo karty (PAN).
expiryHintPlaceholder text v poli pro datum platnosti (napr. MM/RR).
cvvHintPlaceholder text v poli pro CVV kód.
fullNameHintPlaceholder text v poli pro jméno držitele karty.
panInvalidErrorChybová zpráva zobrazená pod PAN poľom pri zadání neplatného čísla karty.
expiryInvalidMonthErrorChybová zpráva zobrazená pod poľom expirace pri zadání neplatného měsíce (napr. 13).
expiryExpiredErrorChybová zpráva zobrazená pod poľom expirace, když je karta prošlá.
fullNameRequiredErrorChybová zpráva zobrazená pod poľom jména, ak není vyplněno.
payButtonTextText platebního tlačidla v klidovém (aktivním) stavu.
payButtonProcessingTextText platebního tlačidla počas spracovania platby.
statusPaidZpráva zobrazená v SecurePaymentStatusView pri úspěšné platbě.
statusPendingZpráva zobrazená v SecurePaymentStatusView, když platba čeká na finální stav.
loadingProcessingTextText zobrazený v SecureLoadingView (překryvná vrstva) počas spracovania platby.
threeDSCancelButtonText tlačidla pro zrušení v dialogu 3D Secure ověření.

Aktuálně dostupné překlady​

PřekladHodnota
AngličtinaTranslation.English
BulharštinaTranslation.Bulgarian
ČeštinaTranslation.Czech
DánštinaTranslation.Danish
EstonštinaTranslation.Estonian
FinštinaTranslation.Finnish
FrancouzštinaTranslation.French
ChorvatštinaTranslation.Croatian
ItalštinaTranslation.Italian
LitevštinaTranslation.Lithuanian
LotyšštinaTranslation.Latvian
MaďarštinaTranslation.Hungarian
NěmčinaTranslation.German
NizozemštinaTranslation.Dutch
NorštinaTranslation.Norwegian
PolštinaTranslation.Polish
PortugalštinaTranslation.Portuguese
RumunštinaTranslation.Romanian
RuštinaTranslation.Russian
ŘečtinaTranslation.Greek
SlovenštinaTranslation.Slovak
SlovinštinaTranslation.Slovenian
ŠpanělštinaTranslation.Spanish
ŠvédštinaTranslation.Swedish
UkrajinštinaTranslation.Ukrainian
VietnamštinaTranslation.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",
    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
)

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).