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.

Upozornění

Při integraci tohoto modulu do SPA aplikace si důkladně prostudujte dokumentaci metod mount() a destroy(). Nesprávná práce s modulem může vést k nepředvídatelnému chování.

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ýška 30px.
• Tlačítko s textem (Buy with Apple Pay, Donate with Apple Pay apod.) – minimální šířka 140px, výška 30px.

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:

1. instance modulu Core získaná v předchozím kroku,
2. 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().

Upozornění

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

// ...
// 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");
}
// ...

reject

// ...
onButtonClick: () => {
  return Promise.reject("Chybný košík");
}
// ...

new Promise(...)

// ...
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í typu ModuleApplePay.
• V případě chyby je Promise odmítnut (catch) s objektem typu Error. V TypeScriptu se doporučuje anotovat chyby v bloku catch jako unknown, protože není zaručeno, že půjde vždy o Error.

Podrobný popis typu ModuleApplePay je uveden v samostatné sekci Použití instance Apple Pay.

Příklady

Úspěch

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.

Chyba

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

canMakePayments()

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.canMakePayments()
.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 (callback uvnitř je bez parametru),
• 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 canMakePayments(), 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>.

Tip

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 (callback uvnitř je bez parametru),
• 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.

Upozornění

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.