Prispôsobenie vzhľadu
Predvolený vzhľad SDK je navrhnutý tak, aby ho bolo možné použiť bez ďalších úprav. Ak však potrebujete vzhľad SDK, najmä karetného formulára, prispôsobiť vizuálnemu štýlu vášho e-shopu, SDK poskytuje niekoľko možností konfigurácie.
SDK pracuje s dvoma vizuálnymi vrstvami, ktoré sa upravujú odlišným spôsobom:
- Tlačidlá Apple Pay a Google Pay — tlačidlá sú vytvárané knižnicami spoločností Apple a Google a umožňujú iba základné prispôsobenie. Pomocou konfiguračného objektu
uiv konfiguračnom parametriapplepayalebogooglepaymožno nastaviť iba farbu a typ tlačidla (text obsiahnutý na tlačidle). Vlastné CSS nemožno použiť, pretože tlačidlá sú renderované oficiálnou knižnicou a nie sú dostupné pre priame stylovanie. - Karetný formulár — polia pre číslo karty, expiráciu a bezpečnostný kód sú z bezpečnostných dôvodov umiestnené v izolovanom iframe. Obsah iframe nie je dostupný pre stylovanie pomocou CSS z nadradenej stránky. Vzhľad karetného formulára sa preto nastavuje prostredníctvom konfiguračného objektu
appearance. Všetky ostatné prvky zobrazené na stránke mimo izolovanéhoiframeje možné stylovať štandardne pomocou vlastného CSS stránky.
Apple Pay
Tlačidlá Apple Pay nemožno stylovať vlastným CSS. Jeho vzhľad možno ovplyvniť iba prostredníctvom konfigurácie ui. Toto obmedzenie vychádza priamo z pravidiel Apple.
applepay.ui
| Parameter | Typ | Povolené hodnoty | Default | Popis |
|---|---|---|---|---|
type | string | plain, add-money, book, buy, check-out, continue, contribute, donate, order, pay, reload, rent, set-up, subscribe, support, tip, top-up | 'pay' | Text/logo zobrazené na tlačidle. |
color | string | black, white, white-with-outline | 'black' | Farebná varianta tlačidla. |
enableResizeListener | boolean | true, false | true | Zapne automatické prispôsobenie tlačidla pri zmene rozmerov kontajnera. |
style | object | – | – | Rozmery a zaoblenie tlačidla — viď tabuľka nižšie. |
applepay.ui.style
Cez voliteľný objekt style možno doplniť rozmery a zaoblenie:
| Parameter | Typ | Default | Popis |
|---|---|---|---|
width | number | – | Šírka v px; ak nie je nastavená, tlačidlo vyplní šírku kontajnera. |
height | number | – | Výška v px; ak nie je nastavená, tlačidlo vyplní výšku kontajnera. |
borderRadius | number | 4 | Zaoblenie rohov v px. |
paddingX | number | 0 | Vodorovný padding vnútri tlačidla v px. |
paddingY | number | 2 | Zvislý padding vnútri tlačidla v px. |
boxSizing | 'border-box' | 'content-box' | 'border-box' | Model rámčeka. |
applepay.payment
Túto konfiguráciu používajte iba ak presne viete, že potrebujete zmeniť predvoleného poskytovateľa pre Apple Pay (predvolený je COMGATE). Ak využívate štandardné nastavenie, tento kľúč vynechajte a nechajte SDK, aby si poskytovateľa zvolilo samo.
| Parameter | Typ | Povinný | Default | Popis |
|---|---|---|---|---|
provider | string | Áno (ak payment uvediete) | 'COMGATE' | Poskytovateľ spracovania Apple Pay. Povolené: 'COMGATE', 'CSOB'. |
providerId | string | Nie | – | ID poskytovateľa (ak sa líši od predvoleného). |
applepay.actions
| Parameter | Typ | Popis |
|---|---|---|
onButtonClick | (moduleId: string) => Promise<void> | Volané po kliknutí na tlačidlo Apple Pay, pred zahájením platby. Možno využiť pre validáciu košíka. Platba sa spustí až po vyriešení vráteného Promise. |
Ukážka konfigurácie
applepay: {
mountPoint: '#cg-applepay-box',
ui: {
type: 'pay',
color: 'black',
enableResizeListener: true,
style: {
width: 240,
height: 45,
borderRadius: 6,
paddingX: 12,
paddingY: 10,
boxSizing: 'border-box',
},
},
//payment: {
//provider: 'COMGATE',
//providerId: 'M0MIPS0001', // or '123456'
//},
actions: {
onButtonClick: async (moduleId) => {
console.log('Apple Pay button clicked', moduleId);
// platba sa spustí až po dokončení funkcie / vyriešení Promise
// možno napríklad aj zastaviť spracovanie
// viac v dokumentácii k onButtonClick nižšie
},
},
}
Zdroje
- Online simulátor — oficiálny nástroj pre testovanie rôznych konfigurácií Apple Pay tlačidla
- Marketing Guidelines — marketingové pokyny, ako správne používať Apple Pay tlačidlá
- Human Interface Guidelines — pokyny pre návrh používateľského rozhrania pre integráciu Apple Pay
Google Pay
Tlačidlá Google Pay nemožno stylovať vlastným CSS. Jeho vzhľad možno ovplyvniť iba prostredníctvom konfigurácie ui. Toto obmedzenie vychádza priamo z pravidiel Google.
googlepay.ui
| Parameter | Typ | Povolené hodnoty | Default | Popis |
|---|---|---|---|---|
type | string | book, buy, checkout, donate, order, pay, plain, subscribe, short | 'plain' | Text/logo zobrazené na tlačidle. |
color | string | black, white | 'black' | Farebná varianta tlačidla. |
enableResizeListener | boolean | true, false | – | Zapne automatické prispôsobenie tlačidla pri zmene rozmerov kontajnera. |
Hodnota short zodpovedá tlačidlu iba s logom (bez textu), buy zobrazí text „Buy with Google Pay".
googlepay.payment
| Parameter | Typ | Povinný | Default | Popis |
|---|---|---|---|---|
googlePayMerchantId | string | Nie (test) / Áno (prod) | – | Merchant ID z Google Pay Business Console. Pre testovanie nie je vyžadované, pre produkciu je povinné. |
provider | string | Nie | 'COMGATE' | Poskytovateľ spracovania Google Pay. Povolené: 'COMGATE', 'CSOB'. |
providerId | string | Nie | – | ID poskytovateľa (ak sa líši od predvoleného). |
googlepay.actions
| Parameter | Typ | Popis |
|---|---|---|
onButtonClick | (moduleId: string) => Promise<void> | Volané po kliknutí na tlačidlo Google Pay, pred zahájením platby. Možno využiť pre validáciu košíka. Platba sa spustí až po vyriešení vráteného Promise. |
Ukážka konfigurácie
googlepay: {
mountPoint: '#cg-googlepay-box',
ui: {
type: 'pay',
color: 'black',
enableResizeListener: true,
},
payment: {
googlePayMerchantId: 'BCR*******ZAV',
//provider: 'COMGATE',
},
actions: {
onButtonClick: async (moduleId) => {
console.log('Google Pay button clicked', moduleId);
// platba sa spustí až po vyriešení tohto Promise
},
},
}
Zdroje
- Online simulátor — oficiálny nástroj pre testovanie rôznych konfigurácií Google Pay tlačidla
- Brand Guidelines — marketingové pokyny, ako správne používať Google Pay tlačidlá
- UX best practices — pokyny pre návrh používateľského rozhrania pre integráciu Google Pay
Karetný formulár
SDK automaticky vkladá predvolené štýly pre karetný kontajner pri mountovaní modulu. Štýly sú vložené na začiatok <head> ako <style> tag — všetky selektory sú obmedzené (scoped) na ID kontajnera, vďaka tomu nedochádza ku kolíziám s ostatnými štýlmi stránky.
- Štýly sú vložené pri volaní
mount()a odstránené pridestroy(). - SDK nepoužíva
!important— stačí definovať pravidlá s rovnakou alebo vyššou špecificitou. - CSS premenné (
--cg-green,--cg-green-hover,--cg-ibox-h,--cg-btn-h) sú scopované pod ID kontajnera a možno ich prepísať vlastným selektorom.
SDK štýly sú vložené na začiatok <head> (pred všetky ostatné <style> a <link>). Vaše vlastné CSS s rovnakou špecificitou preto vždy vyhrá vďaka neskoršiemu poradiu v kaskáde (source order) — bez ohľadu na to, kde na stránke sa nachádza.
Prispôsobenie predvolených štýlov
Prepísať SDK štýly môžete jednoducho vlastným CSS s rovnakou alebo vyššou špecificitou:
Podmienkou úpravy štýlov je zachovanie plnej funkčnosti všetkých prvkov formulára. Všetky prvky musia zostať viditeľné, dostupné a použiteľné.
Skrytie časti formulára, napríklad pomocou pravidla display: none, je považované za porušenie integračných podmienok Comgate a môže viesť k ukončeniu poskytovania služby Checkout SDK.
Príklad — úplné prepísanie všetkých SDK štýlov
Nižšie je uvedený príklad CSS pokrývajúci všetky štýly, ktoré SDK vkladá. Môžete si vybrať len tie pravidlá, ktoré chcete prepísať.
/* CSS premenné a základný rámec kontajnera */
#cg-card-box {
/* --cg-green: #2abd4f; */
/* --cg-green-hover: #38c65d; */
/* --cg-ibox-h: 140px; */
/* --cg-btn-h: 44px; */
/* border: 1px solid #f0f0f0; */
/* background: #f2f2f2; */
/* border-radius: 5px; */
/* padding: 15px; */
/* max-width: 450px; */
}
/* Oblasť formulára pre zadanie karty */
#cg-card-box-ibox {
/* min-height: var(--cg-ibox-h); */
}
#cg-card-box-ibox iframe {
/* display: block; */
/* width: 100%; */
/* height: var(--cg-ibox-h); */
/* border: none; */
}
/* Ikony karetných sietí */
#cg-card-box .cg-card-icons {
/* display: flex; */
/* align-items: center; */
/* gap: 6px; */
/* padding: 5px 0; */
}
#cg-card-box .cg-card-icons .cg-card-icon {
/* display: inline-flex; */
/* align-items: center; */
/* justify-content: center; */
/* width: 30px; */
/* height: 19px; */
}
#cg-card-box .cg-card-icons .cg-card-icon img {
/* width: 30px; */
/* height: 19px; */
/* object-fit: contain; */
}
/* Tlačidlo pre odoslanie platby */
#cg-card-box-button button {
/* transition: background-color 0.1s ease-in-out; */
/* display: inline-flex; */
/* align-items: center; */
/* justify-content: center; */
/* width: 100%; */
/* height: var(--cg-btn-h); */
/* padding: 14px 10px; */
/* margin-top: 10px; */
/* border: none; */
/* border-radius: 5px; */
/* background: var(--cg-green); */
/* color: #fff; */
/* font-size: 14px; */
/* font-weight: 700; */
/* cursor: pointer; */
}
#cg-card-box-button button:hover {
/* background: var(--cg-green-hover); */
}
/* Ikona zámku vnútri tlačidla */
#cg-card-box-button button .cg-button-lock {
/* width: 17px; */
/* flex-shrink: 0; */
/* margin-right: 6px; */
}
/* Ikona fajočky vnútri tlačidla (stav zaplatené) */
#cg-card-box-button button .cg-button-tick {
/* width: 14px; */
/* height: 14px; */
/* flex-shrink: 0; */
/* margin-right: 6px; */
}
/* Spinner vnútri tlačidla (počas spracovania platby) */
#cg-card-box-button button .cg-button-spinner {
/* display: inline-block; */
/* width: 16px; */
/* height: 16px; */
/* margin-right: 8px; */
/* border: 2px solid rgba(255,255,255,0.35); */
/* border-top-color: #fff; */
/* border-radius: 50%; */
/* animation: cg-card-spin .6s linear infinite; */
/* vertical-align: middle; */
}
/* Tlačidlo — disabled stav */
#cg-card-box-button button.disabled-btn,
#cg-card-box-button button.disabled-btn:hover,
#cg-card-box-button button.disabled-btn:active,
#cg-card-box-button button.disabled-btn:focus {
/* opacity: 0.65; */
/* cursor: default; */
/* background: var(--cg-green); */
}
/* Loader v oblasti tlačidla */
#cg-card-box-button .cg-card-button-loader {
/* display: flex; */
/* align-items: center; */
/* justify-content: center; */
/* min-height: var(--cg-btn-h); */
/* padding: 12px 0; */
}
#cg-card-box-button .cg-card-button-loader-spinner {
/* display: inline-block; */
/* width: 24px; */
/* height: 24px; */
/* border: 3px solid rgba(0,0,0,0.15); */
/* border-top-color: var(--cg-green); */
/* border-radius: 50%; */
/* animation: cg-card-spin .6s linear infinite; */
}
/* Chybový stav formulára */
#cg-card-box .cg-card-error {
/* display: flex; */
/* flex-direction: column; */
/* align-items: center; */
/* justify-content: center; */
/* gap: 10px; */
/* min-height: var(--cg-ibox-h); */
/* padding: 20px 16px; */
/* text-align: center; */
/* color: #555; */
/* font-size: 13px; */
/* line-height: 1.55; */
}
/* Ikona chybového stavu (SVG cez background-image) */
#cg-card-box .cg-card-error::before {
/* content: ''; */
/* display: block; */
/* width: 40px; */
/* height: 40px; */
/* flex-shrink: 0; */
/* background: url("...") center / contain no-repeat; */
}
#cg-card-box .cg-card-error-retry {
/* display: inline-block; */
/* margin-top: 2px; */
/* color: var(--cg-green); */
/* font-size: 13px; */
/* font-weight: 600; */
/* text-decoration: none; */
/* cursor: pointer; */
}
#cg-card-box .cg-card-error-retry:hover {
/* text-decoration: underline; */
}
/* Príplatok za platobnú metódu */
#cg-card-box .cg-surcharge {
/* margin-top: 8px; */
/* font-size: 14px; */
/* line-height: 1.4; */
}
#cg-card-box .cg-surcharge-info {
/* display: flex; */
/* justify-content: space-between; */
/* align-items: center; */
}
#cg-card-box .cg-surcharge-amount {
/* font-weight: 600; */
/* color: #dc291e; */
}
#cg-card-box .cg-surcharge-toggle {
/* font-size: 14px; */
/* margin-top: 0; */
/* display: inline-block; */
/* color: inherit; */
/* text-decoration: underline; */
/* outline: none; */
}
#cg-card-box .cg-surcharge-detail {
/* font-size: 14px; */
/* color: rgba(0, 0, 0, 0.5); */
/* transition: opacity 0.25s ease, max-height 0.25s ease 0.25s, margin-top 0.25s ease 0.25s; */
/* opacity: 0; */
/* overflow: hidden; */
/* max-height: 0; */
/* margin: 0; */
}
#cg-card-box .cg-surcharge-detail.cg-surcharge-detail--expanded {
/* transition: max-height 0.25s ease, margin-top 0.25s ease, opacity 0.25s ease; */
/* margin-top: 10px; */
/* max-height: 200px; */
/* opacity: 1; */
}
#cg-card-box .cg-surcharge-blocked {
/* color: #c0392b; */
}
#cg-card-box .cg-surcharge-blocked p {
/* margin: 0; */
}
/* Utility — skrytie prvku */
#cg-card-box .cg-hidden {
/* display: none !important; */
}
Loading stav karetného formulára
SDK štýly sa vložia až po stiahnutí a spustení JavaScriptu. Ak chcete používateľovi zobraziť loading spinner okamžite po vykreslení stránky (ešte pred tým, než sa SDK stihne načítať), pridajte hlavnému kontajneru karty triedu is-loading — SDK ju po namountovaní automaticky odstráni.
Loading štýly sú voliteľné — bez nich sa kontajner zobrazí ako prázdny priestor do času, než SDK načíta formulár. Ak vám to nevadí, túto sekciu môžete preskočiť.
- V kontajneri
- Mimo kontajnera
<div id="cg-card-box" class="is-loading">
<div id="cg-card-box-ibox"></div>
<div id="cg-card-box-button">
<button type="button">Zaplatiť</button>
</div>
</div>
<div id="cg-card-box" class="is-loading">
<div id="cg-card-box-ibox"></div>
</div>
<!-- tlačidlo kdekoľvek inde na stránke -->
<div id="cg-card-box-button" class="is-loading">
<button type="button">Zaplatiť</button>
</div>
CSS pre loading spinner
Vložte do svojho CSS nasledujúce pravidlá:
/* Loading state — spinner zobrazený okamžite z HTML, než sa SDK naloaduje */
#cg-card-box.is-loading #cg-card-box-ibox {
position: relative;
min-height: 140px;
}
#cg-card-box.is-loading #cg-card-box-ibox::before {
content: '';
position: absolute;
inset: 0;
margin: auto;
width: 25px;
height: 25px;
background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='none' stroke='%23888888' stroke-linecap='round' stroke-linejoin='round' stroke-width='2' viewBox='0 0 24 24'%3E%3Crect width='18' height='11' x='3' y='11' rx='2' ry='2'/%3E%3Cpath d='M7 11V7a5 5 0 0 1 10 0v4'/%3E%3Cg transform='translate(0 -.38)'%3E%3Ccircle cx='12.1' cy='16.067' r='.472' style='fill:%23888888;stroke-width:1.25646;'/%3E%3Cpath d='M12.079 16.62h.042v1.342h-.042z' style='fill:%23888888;stroke-width:1.65753;'/%3E%3C/g%3E%3C/svg%3E");
background-size: contain;
background-repeat: no-repeat;
background-position: center;
z-index: 1;
}
#cg-card-box.is-loading #cg-card-box-ibox::after {
content: '';
position: absolute;
inset: 0;
margin: auto;
width: 63px;
height: 63px;
border: 3px solid #e4e4e4;
border-top-color: #999;
border-radius: 50%;
animation: cg-card-spin 1.2s cubic-bezier(0.5, 0, 0.5, 1) infinite;
}
#cg-card-box.is-loading #cg-card-box-button {
display: none;
}
/* Varianta: tlačidlo mimo kontajnera */
#cg-card-box-button.is-loading {
display: none;
}
@keyframes cg-card-spin { to { transform: rotate(360deg); } }
Vstupné polia
Formulár pre zadávanie karetných dát beží v zabezpečenom iframe, a preto je jeho prispôsobenie možné výhradne prostredníctvom konfigurácie appearance v parametri card. Objekt appearance umožňuje nastaviť farby, fonty, zaoblenie, odsadenie — viď prehľad nižšie.
Hierarchia aplikácie štýlov: predvolené CSS → variables → rules (každá vrstva prepisuje predchádzajúcu).
Hlavný objekt appearance
| Parameter | Typ | Povinný | Popis |
|---|---|---|---|
version | number | Áno | Verzia appearance konfigurácie — zvýšte 1 pri každej zmene. |
variables | object | Nie | Designové atribúty (CSS custom properties) — viď tabuľka nižšie. |
rules | object | Nie | Per-element CSS prepisy — viď tabuľka nižšie. |
appearance.variables — designové atribúty
Atribúty nastavujú CSS custom properties na :root vnútri iframe. Ovplyvnia všetky prvky formulára naraz.
| Parameter | Popis |
|---|---|
colorText | Farba textu (inputy, popisky). |
colorBackground | Farba pozadia inputov. |
colorPrimary | Primárna farba — rámček pri focuse, aktívne prvky. |
colorDanger | Farba nebezpečia — rámček nevalidného poľa, text chybovej hlášky. |
colorPlaceholder | Farba placeholder textu. |
borderColor | Predvolená farba rámčeka inputu. |
borderRadius | Zaoblenie rohov inputu. |
fontFamily | Font formulára (obmedzené na povolený allowlist). |
fontSize | Veľkosť písma inputu. |
spacing | Padding inputov a medzery medzi poľami. |
appearance.rules — per-element CSS prepisy
Každý kľúč v objekte rules cieli na konkrétny vizuálny element formulára:
| Kľúč | Čo styluje |
|---|---|
container | Koreňový kontajner formulára ([data-slot="container"]) |
label | Popisok nad inputom ([data-slot="label"]) |
input | Input v predvolenom stave ([data-slot="input"]) |
inputFocus | Input v stave focus ([data-slot="input"][data-state="focus"]) |
inputInvalid | Input s nevalidnou hodnotou ([data-slot="input"][data-invalid]) |
error | Chybová správa pod inputom ([data-slot="error"]) |
Každý kľúč prijíma objekt s povolenými CSS vlastnosťami (SafeStyle):
| CSS vlastnosť | Typ | Príklad |
|---|---|---|
color | string | '#111827' |
backgroundColor | string | '#ffffff' |
borderColor | string | '#e5e7eb' |
borderRadius | string | '6px' |
fontFamily | string | 'Arial, sans-serif' |
fontSize | string | '14px' |
fontWeight | string | '500' |
lineHeight | string | '1.5' |
letterSpacing | string | '0.5px' |
paddingBlock | string | '10px' |
paddingInline | string | '12px' |
boxShadow | string | '0 0 0 2px rgba(0, 102, 204, 0.25)' |
SDK interne validuje štýly a odmieta nebezpečné hodnoty. Neplatný štýl je ignorovaný a SDK vypíše varovanie do konzoly.
Fonty možno nastaviť také, ktoré sú obsiahnuté v rámci operačného systému (napr. Arial, Helvetica, sans-serif). Nemožno načítavať externé fonty pomocou @font-face alebo z CDN.
Ukážka konfigurácie
card: {
mountPoint: '#cg-card-box',
appearance: {
version: 1, // zvýšte o 1 pri každej zmene
variables: {
colorText: '#111827',
colorBackground: '#ffffff',
colorPrimary: '#0891b2',
colorDanger: '#dc2626',
colorPlaceholder: '#9ca3af',
borderColor: '#e5e7eb',
borderRadius: '4px',
fontFamily: 'Arial, sans-serif',
fontSize: '14px',
spacing: '8px',
},
rules: {
container: { backgroundColor: '#f9fafb' },
label: { color: '#374151', fontWeight: 'bold', fontSize: '12px' },
input: { backgroundColor: '#ffffff', borderColor: '#e5e7eb', color: '#111827', paddingBlock: '6px', paddingInline: '8px' },
inputFocus: { borderColor: '#0891b2' },
inputInvalid: { borderColor: '#dc2626' },
error: { color: '#dc2626', fontSize: '11px' },
},
},
}
Dynamická zmena vzhľadu za behu
Vzhľad karetného formulára možno meniť aj po inicializácii — napríklad pri prepnutí medzi svetlým a tmavým režimom. Použite metódu setAppearance() na inštancii Card modulu:
const result = await useCheckout({ /* ... */ });
const instanceCard = result.card?.instance;
// Prepnutie do dark mode
instanceCard.setAppearance({
version: 1, // zvýšte o 1 pri každej zmene
variables: {
colorText: '#e5e7eb',
colorBackground: '#2c2c2e',
colorPrimary: '#a1a1aa',
colorDanger: '#f87171',
colorPlaceholder: '#52525b',
borderColor: '#3f3f46',
borderRadius: '4px',
},
rules: {
container: {
backgroundColor: '#0f0f0f',
},
label: {
color: '#71717a',
fontWeight: '500',
},
input: {
backgroundColor: '#2c2c2e',
color: '#e5e7eb',
borderColor: '#3f3f46',
},
inputFocus: {
borderColor: '#a1a1aa',
boxShadow: '0 0 0 2px rgba(161, 161, 170, 0.15)',
},
inputInvalid: {
borderColor: '#f87171',
boxShadow: '0 0 0 2px rgba(248, 113, 113, 0.15)',
},
error: {
color: '#f87171',
},
},
});
Metóda prijíma rovnaký formát ako appearance v konfigurácii card. Zmena sa prejaví okamžite.
Zmena jazyka
Jazyk celého SDK — vrátane textov tlačidiel a chybových hlášok — možno zmeniť za behu volaním changeLocale() na inštancii Core modulu:
const result = await useCheckout({ /* ... */ });
const instanceCore = result.core?.instance;
// Prepnutie jazyka na angličtinu
instanceCore.changeLocale('en');