Apple Pay modul
Modul Apple Pay rozšiřuje funkčnost Checkout SDK o možnost přijímat platby prostřednictvím Apple Pay. Využívá instanci modulu Core jako referenční objekt a navazuje na jeho konfiguraci i logiku zpracování plateb. Jeho úkolem je zajistit inicializaci, spuštění a obsluhu platebního procesu přes Apple Pay v prostředí prohlížeče nebo mobilní aplikace.
Modul Apple Pay rozšiřuje Checkout SDK o možnost přijímat platby prostřednictvím Apple Pay – platební metody určené pro uživatele zařízení Apple. Funguje na principu napojení na instanci Core, se kterou sdílí konfiguraci i stav, a proto je nutné mít Core vždy inicializován jako první.
Apple Pay se vyznačuje vysokou mírou bezpečnosti, protože využ ívá biometrické ověření (Face ID, Touch ID) nebo zabezpečený přístupový kód zařízení.
Použití modulu Apple Pay je vhodné zejména:
- pokud cíloví zákazníci používají zařízení Apple (iPhone, iPad, MacBook neob iMac),
- pokud je potřeba nabídnout rychlou a jednoduchou platbu s minimálním počtem kroků,
- pokud je požadována podpora moderních platebních metod přímo v prohlížeči nebo aplikaci.
Díky tomu lze modul Apple Pay bez komplikací kombinovat s dalšími moduly (např. Google Pay) a poskytnout zákazníkovi více variant dokončení platby v rámci jedné integrace.
Příprava elementu pro vykreslení
Pro správné zobrazení tlačítka Apple Pay je nutné mít na stránce připravený HTML element, do kterého bude tlačítko vloženo metodou mount()
.
Tento prvek slouží jako kontejner, který modul využije k vytvoření a umístění nativního tlačítka.
Doporučený element
- Nejvhodnější je použít element typu
<div>
. - Element by měl být součástí DOMu v okamžiku volání metody
mount()
. - Pokud je použit virtuální element (např. v rámci některých frameworků), SDK jej akceptuje. Pro spolehlivé zobrazení se preferuje již vyrenderovaný prvek.
Technické parametry
Apple umožňuje přizpůsobit velikost tlačítka vizuálnímu stylu webu. Přesto je nutné dodržet minimální rozměry:
- Tlačítko bez textu (plain) – minimální šířka
100px
, výška30px
. - Tlačítko s textem (Buy with Apple Pay, Donate with Apple Pay apod.) – minimální šířka
140px
, výška30px
.
Doporučení pro implementaci:
- Responzivita: tlačítko se automaticky přizpůsobuje rozměrům kontejneru, do kterého je vloženo. Velikost proto určujete především nastavením kontejneru.
- Zarovnání: umístěte tlačítko tak, aby bylo snadno viditelné a jasně rozpoznatelné jako platební prvek.
- Viewport: doporučuje se použít tag
<meta name="viewport" content="width=device-width, initial-scale=1">
, aby na mobilních zařízeních nedocházelo k nechtěnému zmenšení či zvětšení tlačítka. - Výška a šířka:
Minimální velikostMinimální doporučená velikost | Doporučená velikost | Jednotné s Apple Pay | ||
---|---|---|---|---|
Desktop | short | 100 × 30 px | 160 × 45 px | 160 × 45 px |
pay , ... | 140 × 30 px | 220 × 45 px | 240 × 45 px | |
Mobil | short | 100 × 30 px | 160 × 50 px | 160 × 50 px |
pay , ... | 140 × 30 px | 220 × 50 px | 240 × 50 px |
⚠️ Poznámka: Google Pay vyžaduje větší minimální rozměry tlačítka než Apple Pay. Při implementaci obou platebních metod je proto nutné zvolit kompromisní rozměr, který vyhoví oběma službám, a zároveň zajistit dostatečný prostor v layoutu stránky.
Omezení a požadavky
- Do jednoho kontejneru lze vykreslit pouze jedno tlačítko Apple Pay.
- Apple Pay tlačítko má pevně daný vzhled (barvy, tvary, texty). Tyto vlastnosti lze měnit pouze prostřednictvím konfigurace
TApplePayModuleConfigUi
. - V závislosti na zvoleném typu tlačítka je nutné přizpůsobit i jeho rozměry. Varianty s textem vyžadují širší prostor než verze zobrazující pouze logo.
- Je nutné dodržovat oficiální Marketing Guidelines a Human Interface Guidelines, které určují pravidla pro vzhled, umístění a použití tlačítka.
ℹ️ Více informací o minimálních velikostech a designových požadavcích naleznete v oficiální dokumentaci Apple Pay.
Před vytvořením instance
Stejně jako pro Core platí i pro ApplePay, že jakmile Loader úspěšně stáhne všechny moduly pomocí metody loadComgateCheckout()
a je vrácen Promise v bloku .then()
, lze využít v odpovědi namapované funkce k vytvoření instance modulu ApplePay. Postup je tedy velmi podobný.
Z předchozí kapitoly již známe strukturu odpovědi metody loadComgateCheckout()
. Díky tomu lze přímo využít namapované funkce response.applepay.create()
a response.applepay.version()
.
create()
Vytvoří instanci třídy ModuleApplePay a provede základní inicializaci modulu.
Jakmile je vše připraveno, funkce vrací Promise
s instancí třídy ModuleApplePay.
- Přijímá 2 parametry:
- instanci modulu Core,
- objekt s konfiguračními parametry.
- Vrací
Promise
s instancí třídy ModuleApplePay.
Použití
response.applepay.create(coreInstance, {
ui: {
color: 'black',
type: 'plain'
},
actions: {
onButtonClick: () => { console.log('Apple Pay onButtonClick') }
}
})
.then((apInstance) => {
const instanceApplePay = apInstance;
})
.catch((error) => {
console.error("Comgate Checkout: chyba při vytváření instance Apple Pay", error);
});
Parametry
Funkce vyžaduje dva konfigurační parametry:
- instance modulu Core získaná v předchozím kroku,
- konfigurační objekt typu
TApplePayModuleConfig
.
Typ TApplePayModuleConfig
Atribut | Typ | Povinný | Default | Popis |
---|---|---|---|---|
ui | TApplePayModuleConfigUi | Ne | – | Konfigurace vzhledu tlačítka Apple Pay. |
actions | TApplePayModuleConfigActions | Ne | – | Definice handlerů, které se volají během procesu Apple Pay. |
Typ TApplePayModuleConfigUi
Atribut | Typ | Povinný | Default | Popis |
---|---|---|---|---|
type | string | Ne | "pay" | Typ tlačítka určující jeho vzhled (logo a text). Více v oficiální dokumentaci Apple Pay. |
color | string | Ne | "black" | Styl barevného provedení tlačítka (černé, bílé nebo bílé s černým rámečkem). Více v oficiální dokumentaci Apple Pay. |
ℹ️ Náhled jednotlivých variant je možné ověřit v oficiálním simulátoru Apple Pay.
Povolené hodnoty pro type
add-money | book | buy | check-out | continue | contribute | donate | order | pay |
plain | reload | rent | set-up | subscribe | support | tip | top-up |
Povolené hodnoty pro color
black | white | white-outline |
Typ TApplePayModuleConfigActions
Atribut | Typ | Povinný | Default | Popis |
---|---|---|---|---|
onButtonClick | TApplePayOnButtonClickHandler | Ne | – | Handler vyvolaný při kliknutí na tlačítko Apple Pay, ještě před zahájením platebního procesu. |
Typ TApplePayOnButtonClickHandler
Prostřednictvím handleru mapovaného atributem onButtonClick
je e-shop informován o kliknutí na tlačítko Apple Pay.
Tento handler se spouští ještě před samotným zahájením platebního procesu a lze jej využít například pro provedení posledních kontrol, validací nebo úpravu rozhraní.
type TApplePayOnButtonClickHandler = () => Promise<void>;
Návratová hodnota je typu Promise<void>
, což umožňuje provést rychlé asynchronní operace před zahájením platby.
V handleru je možné vrátit Promise.resolve()
, Promise.reject()
nebo new Promise(...)
, který bude vyřešen až později.
Zpracování vždy vyčkává na dokončení daného Promise
. Pokud funkce neobsahuje žádný return
, výchozí chování je ekvivalentní k Promise.resolve()
.
Pokud akce neproběhne v dostatečně krátkém čase, může Apple Pay vyhodnotit, že pokračování není možné, neboť od fyzického kliknutí uplynula příliš dlouhá doba. Apple Pay zároveň neumožňuje zahájit platbu prostřednictvím virtuálního kliknutí vyvolaného kódem a tuto skutečnost striktně ověřuje.
Příklady
- resolve
- reject
- new Promise(...)
// ...
// všechny níže uvedné ukázky zajistí resolve
// v1 – prázdná funkce
onButtonClick: () => {}
// v2 – explicitní return bez hodnoty
onButtonClick: () => {
return;
}
// v3 – návrat jiného typu než void je interně ignorován a vyhodnocen jako resolve
onButtonClick: () => {
return true;
}
// v4 – explicitní návrat Promise.resolve()
onButtonClick: () => {
return Promise.resolve();
}
// v5 – funkce s vedlejším efektem (log) bez návratu
onButtonClick: () => {
console.log("Apple Pay onButtonClick");
}
// ...
// ...
onButtonClick: () => {
return Promise.reject("Chybný košík");
}
// ...
// ...
onButtonClick: () => {
return new Promise((resolve, reject) => {
setTimeout(() => {
resolve(); // po 500 milisekundách proveď resolve
// reject(); // nebo reject
}, 500);
});
}
// ...
Návratová hodnota
Funkce vždy vrací objekt typu
Promise<ModuleApplePay>
.
- V případě úspěchu je
Promise
vyřešen s instancí typuModuleApplePay
. - V případě chyby je
Promise
odmítnut (catch
) s objektem typuError
. V TypeScriptu se doporučuje anotovat chyby v blokucatch
jakounknown
, protože není zaručeno, že půjde vždy oError
.
Podrobný popis typu ModuleApplePay
je uveden v samostatné sekci Použití instance Apple Pay.
Příklady
- Úspěch
- Chyba
V případě úspěšného vytvoření instance modulu ApplePay je vrácen objekt třídy ModuleApplePay
.
Jeho metody a použití jsou popsány v sekci Použití instance Apple Pay.
V případě, že se instanci třídy modulu Apple Pay nepodaří vytvořit, je prostřednictvím catch
vrácen objekt typu Error
.
V prostředí TypeScript se doporučuje anotovat chyby v bloku catch
jako unknown
.
version()
Vrací verzi staženého modulu Apple Pay jako string
.
⚠️ Vrací verzi modulu
Apple Pay
, nikoli verzi celého Comgate Checkout SDK.
Použití
const applepayVersion = response.applepay.version();
console.log(applepayVersion) // vypíše např. 2.0.12
Parametry
Funkce nepřijímá žádné parametry.
Návratová hodnota
Návratovou hodnotou je vždy string
obsahující verzi ve formátu major.minor.patch
.
Příklady
Ukázka struktury odpovědi:
"1.0.12"
Instance ApplePay
Služba Apple Pay je vystavěna nad vrstvou Core, ze které čerpá sdílenou funkcionalitu a servisní logiku. Díky tomuto propojení je možné udržet jednotnou konfiguraci, správu stavu a konzistentní chování napříč celým Checkout SDK.
ApplePay
představuje funkční modul, se kterým vývojář aktivně pracuje při integraci platební metody.
Obsahuje sadu metod, jejichž volání je nezbytné k dosažení funkční implementace a správnému zajištění platebního procesu.
canMakePayment()
Metoda canMakePayments()
slouží k ověření, zda je možné na konkrétním zařízení uživatele spustit platební tok Apple Pay.
Vrací hodnotu typu boolean
, která informuje, zda je služba v daném prostředí dostupná.
Je důležité zdůraznit, že výsledek této metody nezaručuje, že uživatel má v aplikaci Wallet uloženou platnou platební kartu. Ověřuje pouze, zda je možné Apple Pay na zařízení spustit a využít jej pro inicializaci platebního procesu.
- Nepřijímá žádný parametr.
- Vrací objekt
Promise<void>
.
Použití
instanceApplePay.canMakePayment()
.then(() => {
// paltbu lze realizovat
})
.catch((error: unknown) => {
// platbu nelze realizovat
console.error('Comgate Checkout: Platbu nelze realizovat.', error);
});
Parametry
Metoda nepřijímá žádný parametr.
Návratová hodnota
Návratovou hodnotou je objekt typu Promise<void>
,
který oznamuje výsledek kontroly prostředí pro provádění plateb:
then
– je voláno v případě, že prostředí umožňuje provedení platby,catch
– pokud dojde k chybě nebo je vyhodnoceno, že v daném prostředí platbu provést nelze.
Příklady
- Chyba
Error('The web browser does not support Apple Pay version 4.')
mount()
Metoda mount
slouží k zavěšení (vykreslení) tlačítka Apple Pay do vybraného HTML prvku na stránce.
Zajišťuje vytvoření a inicializaci nativního tlačítka podle konfigurace zadané v TApplePayModuleConfig
.
Po úspěšném provolání metody je tlačítko plně funkční a připravené reagovat na interakci uživatele.
Metoda se obvykle volá po vytvoření instance modulu Apple Pay a po volání metody canMakePayment()
, jako finální krok inicializace.
Opakované volání mount()
není vhodné a může vést k nestabilnímu chování.
Prvek předaný metodě mount
slouží jako kontejner, do něhož je vloženo tlačítko Apple Pay.
Doporučuje se použít element typu <div>
, který je již součástí DOMu.
Více informací o vlastnostech a požadavcích na element pro vykreslení tlačítka Apple Pay naleznete v sekci Element pro vykreslení.
- Přijímá jediný parametr typu
Element[]
, v němž je očekáván právě jeden prvek pole. - Vrací objekt typu
Promise<TServiceMountResponse>
.
V případě složitějších scénářů je nutné předchozí instanci uvolnit voláním metody destroy()
.
Tímto postupem se předejde možnému nepředvídatelnému chování.
Použití
const apMountElement = document.querySelector("#applepay-mount-element");
if (apMountElement) {
instanceApplePay.mount([apMountElement])
.then(() => {
console.log('Tlačítko je připraveno');
})
.catch((error: unknown) => {
// při mountování vznikla chyba
console.error('Comgate Checkout: tlačítko se nepodařilo namountovat.', error);
});
} else {
console.error("Comgate Checkout: Mount point nebyl nalezen.");
}
Parametry
Metoda přijímá jediný parametr, kterým je Element[]
(pole prvků typu Element
).
Při zpracování je využita pouze první položka tohoto pole, všechny ostatní jsou ignorovány.
Prvek předaný v parametru je použit pro vložení tlačítka Apple Pay.
Doporučuje se, aby byl tento element typu <div>
.
Více informací o vlastnostech a požadavcích na prvek pro vykreslení tlačítka Apple Pay naleznete výše v sekci Element pro vykreslení.
ℹ️ Typ
Element
může představovat i virtuální prvek, který v dané chvíli ještě není propsán v DOMu. Přesto se doporučuje vkládat tlačítko do již vyrenderovaného elementu, aby bylo zajištěno jeho správné zobrazení a funkčnost.
Návratová hodnota
Návratovou hodnotou je objekt typu Promise<void>
,
který oznamuje výsledek vložení tlačítka do html elementu:
then
– je voláno v případě úspěšného vložení tlačítka do stránky,catch
– pokud dojde k chybě nebo z nějakého důvodu nebylo možné tlačítko do elementu vložit.
Příklady
- Chyba
Error('The service is already mounted. Please unmount it first.')
destroy()
Metoda destroy
slouží k odpojení a odstranění tlačítka Apple Pay z DOMu a k uvolnění souvisejících prostředků.
Používá se zejména v SPA aplikacíchSingle Page Application - dodávají dynamický obsah pomocí Javascriptu (React, Vue, ...). a dále ve složitějších scénářích, kdy je potřeba vytvořit novou instanci Apple Pay, nebo při ukončení práce s modulem Apple Pay.
- Metoda nepřijímá žádné parametry.
- Vrací
void
.
SPA
Pokud používáte SPASingle Page Application – aplikace, které načítají dynamický obsah pomocí JavaScriptu (React, Vue, …)., mějte na paměti, že první instance Core zůstává na pozadí aktivní po celou dobu běhu aplikace.
Po každém zavolání metody mount()
pro tlačítko Apple Pay a následném přechodu na jinou stránku nebo odstranění komponenty, ve které je Apple Pay vykresleno, je nutné provolat také metodu destroy()
.
Pokud by destroy()
nebyla použita (nebo by nedošlo k plnému reloadu stránky), zůstaly by v modulu Checkout SDK aktivní interní listenery a mohly by způsobit běhové problémy.
Po provolání metody destroy()
je instance uvnitř zcela destruována a stává se nefunkční.
Z toho důvodu ji nesmí být dále používána.
Použití
instanceApplePay.destroy();
Parametry
Metoda nepřijímá žádné parametry.
Návratová hodnota
Metoda nevrací žádnou hodnotu, resp. vrací void
.
Implementační ukázka
Kompletní implementační ukázka je dostupná na stránce Příklady implementace.