Instalace a inicializace

Přidání knihovny do projektu

Knihovna je distribuována jako Swift Package. Přidejte ji do svého projektu pomocí Swift Package Manageru.

Xcode

V Xcode otevřete File → Add Package Dependencies…
Zadejte URL repozitáře: https://github.com/comgate-payments/ios-checkout-sdk
Vyberte verzi a target, do kterého má být knihovna přidána.
Po dokončení importujte knihovnu ve zdrojových souborech:

import ComgateSDK

Package.swift

Pokud používáte vlastní Swift Package, přidejte závislost 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")
        ]
    )
]

Upozornění

Knihovna vyžaduje iOS 15.0 nebo novější. Ověřte, že konfigurace vaší aplikace splňuje tento požadavek (Deployment Target v nastavení targetu).

Konfigurace projektu

Apple Pay capability

Pokud plánujete využívat Apple Pay, je nutné v projektu:

V Xcode v záložce Signing & Capabilities přidat capability Apple Pay.
Vybrat (nebo vytvořit) všechny Merchant IDs, které budete používat — typicky jeden pro testovací a jeden pro produkční prostředí.
V Apple Developer portálu (Identifiers → Merchant IDs) zaregistrovat odpovídající merchant identifier ve formátu merchant.<vase-domena>.

V entitlement souboru se objeví seznam povolených merchant identifierů:

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

Podrobnosti k Apple Pay konfiguraci jsou v sekci Apple Pay.

Klávesnice třetích stran

Třetí strany mohou v klávesnici teoreticky odečítat zadávané znaky. Pro maximální bezpečnost karetních dat doporučujeme v AppDelegate zakázat klávesnice třetích stran:

Tip

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

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 Apple Pay plateb.

Parametry konstruktoru

Parametr	Typ	Povinný	Popis
`checkoutId`	`String`	✅	Identifikátor Checkout SDK propojení. Získáte v klientském portálu Comgate.
`threeDSConfig`	`ThreeDSConfig`	✅	Konfigurace 3D Secure (UI, timeout, verze protokolu). Podrobnosti v sekci Karetní data — 3D Secure.
`devMode`	`Bool`		Zapíná vývojový/testovací režim. Výchozí `false`.
`applePayMerchantIdentifier`	`String?`		Apple Pay Merchant ID ve tvaru `merchant.`. Povinný pro Apple Pay.* Pokud je `nil`, Apple Pay je zakázán.
`applePayDisplayName`	`String?`		Název obchodníka zobrazený v Apple Pay platebním sheetu.
`translation`	`Translation`		Překlady textů komponent. Výchozí `.forCurrentLocale()`.
`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).

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 je vytvořit session jako @StateObject v hlavní App nebo root View a v .task modifikátoru asynchronně zavolat initialize():

import SwiftUI
import ComgateSDK

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

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

Informace

Metoda initialize() je async throws a běží na hlavním vlákně (@MainActor). Při chybě vyhodí ComgateException obsahující konkrétní ComgateError.

Stav session (`SessionState`)

ComgateSecureSession vystavuje @Published property state typu SessionState, která v každém okamžiku popisuje aktuální fázi životního cyklu session. Pro jednoduché kontroly je k dispozici vlastnost isInitialized.

Stavy

Stav	Kdy platí
`.notInitialized`	Session byla právě vytvořena. `initialize()` zatím nebyla volána.
`.initializing`	`initialize()` právě probíhá — probíhá síťová komunikace a inicializace 3DS SDK.
`.ready`	Inicializace úspěšně dokončena. Session je připravena zpracovávat platby.
`.failed(ComgateError)`	Inicializace selhala. Asociovaná hodnota nese konkrétní příčinu. Session lze znovu inicializovat voláním `initialize()`.

Vlastnosti session

Vlastnost	Typ	Popis
`state`	`SessionState`	Aktuální stav session (`@Published`).
`isInitialized`	`Bool`	Zkratka: `true` právě tehdy, když `state == .ready`.
`isApplePayConfigured`	`Bool`	`true`, pokud byl předán `applePayMerchantIdentifier` a Apple Pay je dostupný.
`isProcessingPayment`	`Bool`	`true`, dokud probíhá `processPayment(...)` nebo `processApplePayPayment(...)`.
`translation`	`Translation`	Překlady aktuální session (read-only).

Použití v UI (SwiftUI)

struct ContentView: View {
    @ObservedObject var session: ComgateSecureSession

    var body: some View {
        switch session.state {
        case .notInitialized:
            Button("Inicializovat") {
                Task { try? await session.initialize() }
            }
        case .initializing:
            ProgressView()
        case .ready:
            PaymentForm(session: session)
        case .failed(let error):
            VStack {
                Text("Chyba inicializace: \(error.message)")
                Button("Zkusit znovu") {
                    Task { try? await session.initialize() }
                }
            }
        }
    }
}

Chyby při inicializaci

Stav .failed(error) nese ComgateError s popisem příčiny. Nejčastější chyby při inicializaci:

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

Informace

Property state je publikována přes Combine (@Published) a všechny aktualizace probíhají na hlavním vlákně. Stav lze pozorovat přes .onReceive(session.$state) nebo přímo v SwiftUI body.

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, automatickou detekci jazyka zařízení nebo vlastní instanci Translation
Uživatelsky nastavitelné jsou 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/YY`).
`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.
`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ě.
`statusAuthorized`	Zpráva zobrazená v `SecurePaymentStatusView` při autorizované platbě (předautorizace).
`statusPending`	Zpráva zobrazená v `SecurePaymentStatusView`, když platba čeká na finální stav.
`loadingProcessingText`	Text zobrazený v `SecureLoadingView` 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`

let 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",
    statusAuthorized: "Autorizováno",
    statusPending: "Zpracovává se",
    loadingProcessingText: "Zpracovávám platbu…",
    threeDSCancelButton: "Zrušit"
)

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

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

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

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:

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
)

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

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

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

Přidání knihovny do projektu​

Xcode​

Package.swift​

Konfigurace projektu​

Apple Pay capability​

Klávesnice třetích stran​

Vytvoření session​

Parametry konstruktoru​

Inicializace​

Stav session (SessionState)​

Stavy​

Vlastnosti session​

Použití v UI (SwiftUI)​

Chyby při inicializaci​

Překlady (lokalizace)​

Aktuálně dostupné překlady​

Kódy podporovaných jazyků​

Přidání knihovny do projektu

Xcode

Package.swift

Konfigurace projektu

Apple Pay capability

Klávesnice třetích stran

Vytvoření session

Parametry konstruktoru

Inicializace

Stav session (`SessionState`)

Stavy

Vlastnosti session

Použití v UI (SwiftUI)

Chyby při inicializaci

Překlady (lokalizace)

Aktuálně dostupné překlady

Kódy podporovaných jazyků