Google Pay modul

Modul Google Pay rozšiřuje funkčnost Checkout SDK o možnost přijímat platby prostřednictvím Google 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 Google Pay v prostředí prohlížeče nebo mobilní aplikace.

Modul Google Pay rozšiřuje Checkout SDK o možnost přijímat platby prostřednictvím Google Pay – platební metody určené pro uživatele zařízení Android a dalších. 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í.

Google Pay se vyznačuje vysokou mírou bezpečnosti, protože využívá biometrické ověření (sken obličeje, otisk prstu) nebo zabezpečený přístupový kód zařízení.

Použití modulu Google Pay je vhodné zejména:

• 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 Google Pay bez komplikací kombinovat s dalšími moduly (např. Apple 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 Google 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

Google 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 (short) – minimální šířka 90px, výška 40px.
• Tlačítko s textem (Buy with G Pay, Donage with G Pay apod.) – minimální šířka 240px, výška 40px.

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	140 × 40 px	160 × 45 px	160 × 45 px
	pay, ...	240 × 40 px	240 × 45 px	240 × 45 px
Mobil	short	140 × 40 px	160 × 50 px	160 × 50 px
	pay, ...	240 × 40 px	240 × 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 Google Pay.
• Google Pay tlačítko má pevně daný vzhled (barvy, tvary, texty). Tyto vlastnosti lze měnit pouze prostřednictvím konfigurace TGooglePayModuleConfigUi.
• 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í Brand Guidelines a UX best practices, 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 Google Pay.

Před vytvořením instance

Stejně jako pro Core platí i pro GooglePay, ž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 GooglePay. 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.googlepay.create() a response.googlepay.version().

create()

Vytvoří instanci třídy ModuleGooglePay a provede základní inicializaci modulu.

Jakmile je vše připraveno, funkce vrací Promise s instancí třídy ModuleGooglePay.

• Přijímá 2 parametry:
• instanci modulu Core,
• objekt s konfiguračními parametry.
• Vrací Promise s instancí třídy ModuleGooglePay.

Použití

response.googlepay.create(coreInstance, {
  ui: {
    color: 'black',
    type: 'short'
  },
  actions: {
    onButtonClick: () => { console.log('Google Pay onButtonClick') }
  }
})
.then((gpInstance) => {
  const instanceGooglePay = gpInstance;
})
.catch((error) => {
  console.error("Comgate Checkout: chyba při vytváření instance Google 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 TGooglePayModuleConfig.

Typ TGooglePayModuleConfig

Atribut	Typ	Povinný	Default	Popis
ui	TGooglePayModuleConfigUi	Ne	–	Konfigurace vzhledu tlačítka Google Pay.
actions	TGooglePayModuleConfigActions	Ne	–	Definice handlerů, které se volají během procesu Google Pay.

Typ TGooglePayModuleConfigUi

Atribut	Typ	Povinný	Default	Popis
type	string	Ne	"short"	Typ tlačítka určující jeho vzhled (logo a text). Více v oficiální dokumentaci Google 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 Google Pay.

ℹ️ Náhled jednotlivých variant je možné ověřit v oficiálním simulátoru Google Pay.

Povolené hodnoty pro type

book	buy	checkout	donate	order	pay	plain	subscribe
long (stejné jako buy)				short (stejné jako plain)

Povolené hodnoty pro color

black

white

Typ TGooglePayModuleConfigActions

Atribut	Typ	Povinný	Default	Popis
onButtonClick	TGooglePayOnButtonClickHandler	Ne	–	Handler vyvolaný při kliknutí na tlačítko Google Pay, ještě před zahájením platebního procesu.

Typ TGooglePayOnButtonClickHandler

Prostřednictvím handleru mapovaného atributem onButtonClick je e-shop informován o kliknutí na tlačítko Google 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 TGooglePayOnButtonClickHandler = () => 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 Google Pay vyhodnotit, že pokračování není možné, neboť od fyzického kliknutí uplynula příliš dlouhá doba. Google 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("Google 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<ModuleGooglePay>.

• V případě úspěchu je Promise vyřešen s instancí typu ModuleGooglePay.
• 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 ModuleGooglePay je uveden v samostatné sekci Použití instance Google Pay.

Příklady

Úspěch

V případě úspěšného vytvoření instance modulu GooglePay je vrácen objekt třídy ModuleGooglePay. Jeho metody a použití jsou popsány v sekci Použití instance Google Pay.

Chyba

V případě, že se instanci třídy modulu Google 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 Google Pay jako string.

⚠️ Vrací verzi modulu Google Pay, nikoli verzi celého Comgate Checkout SDK.

Použití

const googlepayVersion = response.googlepay.version();
console.log(googlepayVersion) // 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 GooglePay

Služba Google 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.

GooglePay 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 Google 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 Google Wallet uloženou platnou platební kartu. Ověřuje pouze, zda je možné Google 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í

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

Upozornění

TODO - example

Chyba

Error('The web browser does not support Google Pay version 4.')

mount()

Metoda mount slouží k zavěšení (vykreslení) tlačítka Google Pay do vybraného HTML prvku na stránce. Zajišťuje vytvoření a inicializaci nativního tlačítka podle konfigurace zadané v TGooglePayModuleConfig. 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 Google 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 Google 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 Google 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 gpMountElement = document.querySelector("#googlepay-mount-element");

if (gpMountElement) {
  instanceGooglePay.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 Google 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 Google 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

Upozornění

TODO - opravit příklady

Chyba

Error('The service is already mounted. Please unmount it first.')

destroy()

Metoda destroy slouží k odpojení a odstranění tlačítka Google 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 Google Pay, nebo při ukončení práce s modulem Google 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 Google Pay a následném přechodu na jinou stránku nebo odstranění komponenty, ve které je Google 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í

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