Inštalácia a inicializácia

Pridanie knižnice do projektu

Knižnica je distribuovaná ako Swift Package. Pridajte ju do svojho projektu pomocou Swift Package Managera.

Xcode

V Xcode otvorte File → Add Package Dependencies…
Zadajte URL repozitára: https://github.com/comgate-payments/ios-checkout-sdk
Vyberte verziu a target, do ktorého má byť knižnica pridaná.
Po dokončení importujte knižnicu vo zdrojových súboroch:

import ComgateSDK

Package.swift

Ak používate vlastný Swift Package, pridajte závislosť takto:

dependencies: [
    .package(url: "https://github.com/comgate-payments/ios-checkout-sdk", from: "0.1.0")
],
targets: [
    .target(
        name: "MyApp",
        dependencies: [
            .product(name: "ComgateSDK", package: "ComgateSDK")
        ]
    )
]

Upozornenie

Knižnica vyžaduje iOS 15.0 alebo novší. Overte, že konfigurácia vašej aplikácie spĺňa túto požiadavku (Deployment Target v nastavení targetu).

Konfigurácia projektu

Apple Pay capability

Ak plánujete využívať Apple Pay, je potrebné v projekte:

V Xcode v záložke Signing & Capabilities pridať capability Apple Pay.
Vybrať (alebo vytvoriť) všetky Merchant IDs, ktoré budete používať — typicky jeden pre testovacie a jeden pre produkčné prostredie.
V Apple Developer portáli (Identifiers → Merchant IDs) zaregistrovať zodpovedajúci merchant identifier vo formáte merchant.<vasa-domena>.

V entitlement súbore sa objaví zoznam povolených merchant identifierov:

<key>com.apple.developer.in-app-payments</key>
<array>
    <string>merchant.sk.example.production</string>
    <string>merchant.sk.example.sandbox</string>
</array>

Podrobnosti k Apple Pay konfigurácii sú v sekcii Apple Pay.

Klávesnice tretích strán

Tretie strany môžu v klávesnici teoreticky odčítavať zadávané znaky. Pre maximálnu bezpečnosť údajov karty odporúčame v AppDelegate zakázať klávesnice tretích strán:

Tip

func application(
    _ application: UIApplication,
    shouldAllowExtensionPointIdentifier extensionPointIdentifier: UIApplication.ExtensionPointIdentifier
) -> Bool {
    extensionPointIdentifier != .keyboard
}

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,
spracovanie kartových platieb a Apple Pay platieb.

Parametre konštruktora

Parameter	Typ	Povinný	Popis
`checkoutId`	`String`	✅	Identifikátor Checkout SDK prepojenia. Získate v klientskom portáli Comgate.
`threeDSConfig`	`ThreeDSConfig`	✅	Konfigurácia 3D Secure (UI, timeout, verzia protokolu). Podrobnosti v sekcii Údaje karty — 3D Secure.
`devMode`	`Bool`		Zapína vývojový/testovací režim. Predvolene `false`.
`applePayMerchantIdentifier`	`String?`		Apple Pay Merchant ID v tvare `merchant.`. Povinný pre Apple Pay.* Ak je `nil`, Apple Pay je zakázaný.
`applePayDisplayName`	`String?`		Názov obchodníka zobrazený v Apple Pay platobnom sheete.
`translation`	`Translation`		Preklady textov komponentov. Predvolene `.forCurrentLocale()`.
`lang`	`String?`		Kód jazyka (BCP 47 / ISO 639-1) odosielaný s platobnou požiadavkou (napr. `"sk"`, `"en"`). Ak nie je zadaný, použije sa jazyk zariadenia (ak je podporovaný).

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 je vytvoriť session ako @StateObject v hlavnej App alebo root View a v .task modifikátore asynchrónne zavolať initialize():

import SwiftUI
import ComgateSDK

@main
struct MyApp: App {
    @StateObject private var session = ComgateSecureSession(
        checkoutId: "váš-checkout-id",
        threeDSConfig: ThreeDSConfig()  // predvolená 3DS konfigurácia
    )

    var body: some Scene {
        WindowGroup {
            ContentView(session: session)
                .task {
                    do {
                        try await session.initialize()
                    } catch {
                        print("Init failed: \(error)")
                    }
                }
        }
    }
}

Informácie

Metóda initialize() je async throws a beží na hlavnom vlákne (@MainActor). Pri chybe vyhodí ComgateException obsahujúci konkrétny ComgateError.

Stav session (`SessionState`)

ComgateSecureSession vystavuje @Published property state typu SessionState, ktorá v každom okamihu popisuje aktuálnu fázu životného cyklu session. Pre jednoduché kontroly je k dispozícii vlastnosť isInitialized.

Stavy

Stav	Kedy platí
`.notInitialized`	Session bola práve vytvorená. `initialize()` zatiaľ nebola volaná.
`.initializing`	`initialize()` práve prebieha — prebieha sieťová komunikácia a inicializácia 3DS SDK.
`.ready`	Inicializácia úspešne dokončená. Session je pripravená spracovávať platby.
`.failed(ComgateError)`	Inicializácia zlyhala. Asociovaná hodnota nesie konkrétnu príčinu. Session je možné znova inicializovať volaním `initialize()`.

Vlastnosti session

Vlastnosť	Typ	Popis
`state`	`SessionState`	Aktuálny stav session (`@Published`).
`isInitialized`	`Bool`	Skratka: `true` práve vtedy, keď `state == .ready`.
`isApplePayConfigured`	`Bool`	`true`, ak bol odovzdaný `applePayMerchantIdentifier` a Apple Pay je dostupný.
`isProcessingPayment`	`Bool`	`true`, kým prebieha `processPayment(...)` alebo `processApplePayPayment(...)`.
`translation`	`Translation`	Preklady aktuálnej session (read-only).

Použitie v UI (SwiftUI)

struct ContentView: View {
    @ObservedObject var session: ComgateSecureSession

    var body: some View {
        switch session.state {
        case .notInitialized:
            Button("Inicializovať") {
                Task { try? await session.initialize() }
            }
        case .initializing:
            ProgressView()
        case .ready:
            PaymentForm(session: session)
        case .failed(let error):
            VStack {
                Text("Chyba inicializácie: \(error.message)")
                Button("Skúsiť znova") {
                    Task { try? await session.initialize() }
                }
            }
        }
    }
}

Chyby pri inicializácii

Stav .failed(error) nesie ComgateError s popisom príčiny. Najčastejšie chyby pri inicializácii:

Chyba	Kód	Popis
`.deviceRooted`	`DEVICE_ROOTED`	Zariadenie je pravdepodobne jailbreaknuté alebo inak pozmenené. Inicializácia je zablokovaná na ochranu údajov karty. V `devMode` sa táto kontrola preskočí.
`.initNetworkError`	`INIT_NETWORK_ERROR`	Sieťová chyba pri sťahovaní konfigurácie.
`.initUnauthorized`	`INIT_UNAUTHORIZED`	Server vrátil HTTP 401 pri inicializácii — neplatná alebo expirovaná autorizácia.
`.initFailed`	`INIT_FAILED`	Inicializácia zlyhala z iného dôvodu (napr. neplatná odpoveď servera).
`.applicationNotAllowed`	`APPLICATION_NOT_ALLOWED`	Bundle ID aplikácie nie je v zozname povolených aplikácií.

Informácie

Property state je publikovaná cez Combine (@Published) a všetky aktualizácie prebiehajú na hlavnom vlákne. Stav je možné pozorovať cez .onReceive(session.$state) alebo priamo v SwiftUI body.

Preklady (lokalizácia)

Texty komponentov je možné lokalizovať pomocou Translation.

Preklady sa odovzdávajú do ComgateSecureSession parametrom translation
Možné je použiť vstavaný preset, automatickú detekciu jazyka zariadenia alebo vlastnú inštanciu Translation
Používateľsky nastaviteľné sú 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á správa zobrazená pod PAN poľom pri zadaní neplatného čísla karty.
`expiryInvalidMonthError`	Chybová správa zobrazená pod poľom exspirácie pri zadaní neplatného mesiaca.
`expiryExpiredError`	Chybová správa zobrazená pod poľom exspirácie, keď je karta po platnosti.
`fullNameRequiredError`	Chybová správa zobrazená pod poľom mena, ak nie je vyplnené.
`payButtonText`	Text platobného tlačidla v pokojovom (aktívnom) stave.
`payButtonProcessingText`	Text platobného tlačidla počas spracovania platby.
`statusPaid`	Správa zobrazená v `SecurePaymentStatusView` pri úspešnej platbe.
`statusAuthorized`	Správa zobrazená v `SecurePaymentStatusView` pri autorizovanej platbe (predautorizácia).
`statusPending`	Správa zobrazená v `SecurePaymentStatusView`, keď platba čaká na finálny stav.
`loadingProcessingText`	Text zobrazený v `SecureLoadingView` 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`

let translation = Translation(
    panLabel: "Číslo karty",
    expiryLabel: "Platnosť",
    cvvLabel: "CVC/CVV",
    fullNameLabel: "Meno držiteľa",
    panHint: "Číslo karty",
    expiryHint: "MM/RR",
    cvvHint: "CVV",
    fullNameHint: "Meno a priezvisko",
    panInvalidError: "Neplatné číslo karty",
    expiryInvalidMonthError: "Neplatný mesiac",
    expiryExpiredError: "Karta je po platnosti",
    fullNameRequiredError: "Vyplňte meno držiteľa",
    payButtonText: "Zaplatiť",
    payButtonProcessingText: "Spracovávam…",
    statusPaid: "Zaplatené",
    statusAuthorized: "Autorizované",
    statusPending: "Spracováva sa",
    loadingProcessingText: "Spracovávam platbu…",
    threeDSCancelButton: "Zrušiť"
)

let session = ComgateSecureSession(
    checkoutId: "váš-checkout-id",
    threeDSConfig: ThreeDSConfig(),
    translation: translation
)

Príklad so vstavaným prekladom:

let session = ComgateSecureSession(
    checkoutId: "váš-checkout-id",
    threeDSConfig: ThreeDSConfig(),
    translation: .slovak
)

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 je možné 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:

let deviceLang = Locale.current.language.languageCode?.identifier ?? "en"
let resolvedLang = ComgateSecureSession.supportedLanguageCodes.contains(deviceLang) ? deviceLang : "en"

let session = ComgateSecureSession(
    checkoutId: "váš-checkout-id",
    threeDSConfig: ThreeDSConfig(),
    translation: .forLanguageCode(resolvedLang),
    lang: resolvedLang
)

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

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

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

Pridanie knižnice do projektu​

Xcode​

Package.swift​

Konfigurácia projektu​

Apple Pay capability​

Klávesnice tretích strán​

Vytvorenie session​

Parametre konštruktora​

Inicializácia​

Stav session (SessionState)​

Stavy​

Vlastnosti session​

Použitie v UI (SwiftUI)​

Chyby pri inicializácii​

Preklady (lokalizácia)​

Aktuálne dostupné preklady​

Kódy podporovaných jazykov​

Pridanie knižnice do projektu

Xcode

Package.swift

Konfigurácia projektu

Apple Pay capability

Klávesnice tretích strán

Vytvorenie session

Parametre konštruktora

Inicializácia

Stav session (`SessionState`)

Stavy

Vlastnosti session

Použitie v UI (SwiftUI)

Chyby pri inicializácii

Preklady (lokalizácia)

Aktuálne dostupné preklady

Kódy podporovaných jazykov