Skip to main content

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:

  1. 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 ui v konfiguračnom parametri applepay alebo googlepay mož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.
  2. 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ého iframe je 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

ParameterTypPovolené hodnotyDefaultPopis
typestringplain, 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.
colorstringblack, white, white-with-outline'black'Farebná varianta tlačidla.
enableResizeListenerbooleantrue, falsetrueZapne automatické prispôsobenie tlačidla pri zmene rozmerov kontajnera.
styleobjectRozmery a zaoblenie tlačidla — viď tabuľka nižšie.

applepay.ui.style

Cez voliteľný objekt style možno doplniť rozmery a zaoblenie:

ParameterTypDefaultPopis
widthnumberŠírka v px; ak nie je nastavená, tlačidlo vyplní šírku kontajnera.
heightnumberVýška v px; ak nie je nastavená, tlačidlo vyplní výšku kontajnera.
borderRadiusnumber4Zaoblenie rohov v px.
paddingXnumber0Vodorovný padding vnútri tlačidla v px.
paddingYnumber2Zvislý padding vnútri tlačidla v px.
boxSizing'border-box' | 'content-box''border-box'Model rámčeka.

applepay.payment

Informácie

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.

ParameterTypPovinnýDefaultPopis
providerstringÁno (ak payment uvediete)'COMGATE'Poskytovateľ spracovania Apple Pay. Povolené: 'COMGATE', 'CSOB'.
providerIdstringNieID poskytovateľa (ak sa líši od predvoleného).

applepay.actions

ParameterTypPopis
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

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

ParameterTypPovolené hodnotyDefaultPopis
typestringbook, buy, checkout, donate, order, pay, plain, subscribe, short'plain'Text/logo zobrazené na tlačidle.
colorstringblack, white'black'Farebná varianta tlačidla.
enableResizeListenerbooleantrue, falseZapne automatické prispôsobenie tlačidla pri zmene rozmerov kontajnera.
Tip

Hodnota short zodpovedá tlačidlu iba s logom (bez textu), buy zobrazí text „Buy with Google Pay".

googlepay.payment

ParameterTypPovinnýDefaultPopis
googlePayMerchantIdstringNie (test) / Áno (prod)Merchant ID z Google Pay Business Console. Pre testovanie nie je vyžadované, pre produkciu je povinné.
providerstringNie'COMGATE'Poskytovateľ spracovania Google Pay. Povolené: 'COMGATE', 'CSOB'.
providerIdstringNieID poskytovateľa (ak sa líši od predvoleného).

googlepay.actions

ParameterTypPopis
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é pri destroy().
  • 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.
Poradie špecificity

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:

Upozornenie

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.

Tip

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

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

Informácie

Hierarchia aplikácie štýlov: predvolené CSS → variablesrules (každá vrstva prepisuje predchádzajúcu).

Hlavný objekt appearance

ParameterTypPovinnýPopis
versionnumberÁnoVerzia appearance konfigurácie — zvýšte 1 pri každej zmene.
variablesobjectNieDesignové atribúty (CSS custom properties) — viď tabuľka nižšie.
rulesobjectNiePer-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.

ParameterPopis
colorTextFarba textu (inputy, popisky).
colorBackgroundFarba pozadia inputov.
colorPrimaryPrimárna farba — rámček pri focuse, aktívne prvky.
colorDangerFarba nebezpečia — rámček nevalidného poľa, text chybovej hlášky.
colorPlaceholderFarba placeholder textu.
borderColorPredvolená farba rámčeka inputu.
borderRadiusZaoblenie rohov inputu.
fontFamilyFont formulára (obmedzené na povolený allowlist).
fontSizeVeľkosť písma inputu.
spacingPadding 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
containerKoreňový kontajner formulára ([data-slot="container"])
labelPopisok nad inputom ([data-slot="label"])
inputInput v predvolenom stave ([data-slot="input"])
inputFocusInput v stave focus ([data-slot="input"][data-state="focus"])
inputInvalidInput s nevalidnou hodnotou ([data-slot="input"][data-invalid])
errorChybová správa pod inputom ([data-slot="error"])

Každý kľúč prijíma objekt s povolenými CSS vlastnosťami (SafeStyle):

CSS vlastnosťTypPríklad
colorstring'#111827'
backgroundColorstring'#ffffff'
borderColorstring'#e5e7eb'
borderRadiusstring'6px'
fontFamilystring'Arial, sans-serif'
fontSizestring'14px'
fontWeightstring'500'
lineHeightstring'1.5'
letterSpacingstring'0.5px'
paddingBlockstring'10px'
paddingInlinestring'12px'
boxShadowstring'0 0 0 2px rgba(0, 102, 204, 0.25)'
Upozornenie

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');