Výdejní místa v headless obchodech a mobilních aplikacích
Widget košíku od Globe je součástí šablony Shopify. Nativní mobilní aplikace postavená na Storefront API nebo headless webový obchod, například Hydrogen nebo Next.js, šablonu nemá, takže widget není kam vložit. Tento průvodce ukazuje, jak si zákazníci v takových aplikacích vyberou výdejní místo dřív, než se dostanou do pokladny Shopify.
Obě níže popsané možnosti ukládají místo do košíku Storefront API jako atributy košíku. Od té chvíle s ním pokladna i zpracování objednávky zacházejí úplně stejně jako s místem vybraným ve widgetu košíku.
Vyberte možnost
Sekce “Vyberte možnost”| A: Hostovaná stránka pro výběr | B: Storefront API pro výdejní místa | |
|---|---|---|
| Co vytváříte | Otevřete URL ve WebView, vyskakovacím okně nebo iframu | Vlastní mapu nebo seznam v rozhraní vaší aplikace |
| Rozhraní | Mapa, seznam, vyhledávání, geolokace a filtr dopravců od Globe | Vaše vlastní |
| Kdo zapisuje do košíku | Globe | Vaše aplikace, pomocí cartAttributesUpdate |
| Přihlašovací údaj | Žádný. Stránka běží na doméně vašeho obchodu | Veřejný klíč (glb_pk_…) |
| Co řeší vaše aplikace | Otevření stránky a přečtení výsledku | Polohu, vyhledávání, seznam míst a zápis do košíku |
Pokud to chcete mít rychle hotové, začněte možností A. Možnost B zvolte, když výběr musí vypadat a chovat se nativně. Později můžete přejít na druhou možnost: obě zapisují stejné atributy košíku.
Než začnete
Sekce “Než začnete”- Globe je nainstalovaný a má aktivní tarif.
- Headless výběr je pro váš obchod zapnutý. Zapínáme ho pro každý obchod zvlášť: napište nám do chatu podpory v aplikaci. Do té doby se v Nastavení → Headless a mobilní aplikace zobrazuje jen tlačítko Požádat o přístup a stránka pro výběr i Storefront API pro výdejní místa odpovídají, že funkce není zapnutá.
- Máte nastaveného alespoň jednoho dopravce výdejních míst, který je namapovaný na dopravní metody. Viz Přidání výdejních míst.
- Vaše aplikace vytváří košíky přes Storefront API a posílá zákazníky na
checkoutUrlkošíku.
Nastavení Globe
Sekce “Nastavení Globe”V administraci Globe přejděte do Nastavení → Headless a mobilní aplikace.
Pro hostovanou stránku pro výběr
Sekce “Pro hostovanou stránku pro výběr”- V části Stránka pro výběr výdejního místa klikněte na Zapnout.
- V části Návratové adresy klikněte na Přidat návratovou adresu a přidejte všechny adresy, na které může stránka zákazníky vracet:
- deep link aplikace, například
myapp://pickup, - universal link nebo Android App Link, například
https://app.example.com/pickup, - webovou adresu vašeho headless obchodu, například
https://shop.example.com/cart.
- deep link aplikace, například
- Klikněte na Uložit v liště pro uložení.
Návratové adresy jsou volitelné, pokud vaše aplikace čte výsledek jen přes nativní most nebo postMessage. Pro přesměrování jsou povinné a webové domény pro postMessage se berou z návratových adres s https. Viz Return URLs.
Pokud karta hlásí, že Globe potřebuje oprávnění ke košíkům obchodu, otevřete jednou Globe ze Shopify administrace a schvalte aktualizovaná oprávnění. Do té doby stránka zobrazuje, že výběr není dostupný.
Pro Storefront API pro výdejní místa
Sekce “Pro Storefront API pro výdejní místa”- V části Storefront API pro výdejní místa klikněte na Vytvořit klíč a zkopírujte veřejný klíč.
- Volitelně: v části Povolené webové domény klikněte na Přidat doménu a přidejte domény svého webového obchodu, například
https://shop.example.com. Když žádnou doménu nezadáte, klíč může použít jakýkoli web. Nativních aplikací se to nikdy netýká. - Klikněte na Uložit v liště pro uložení.
Veřejný klíč umí jen hledat výdejní místa vašich dopravců, takže ho můžete bezpečně vložit do aplikace nebo do kódu, který běží v prohlížeči. Viz Authentication.
Možnost A: hostovaná stránka pro výběr
Sekce “Možnost A: hostovaná stránka pro výběr”-
Vytvořte nebo načtěte košík zákazníka přes Storefront API a uložte si jeho
id. -
Otevřete tuto URL na doméně svého obchodu:
https://{shop domain}/apps/appfleece-globe/select?cart={URL-encoded cart id}&return_url={allowlisted URL}&state={your value} -
Zákazník vybere místo. Globe ho ověří u dopravce a zapíše atributy košíku.
-
Vaše aplikace dostane výsledek: přesměrování na
return_url, zprávu přes nativní most, nebopostMessage. -
Načtěte košík znovu a pokračujte na
checkoutUrl.
Všechny parametry, zprávy s výsledkem a kód pro iOS, Android, React Native a Hydrogen najdete na stránce Hosted selection page.
Možnost B: Storefront API pro výdejní místa
Sekce “Možnost B: Storefront API pro výdejní místa”- Požádejte zákazníka o polohu, nebo ho nechte posouvat mapou.
- Vyhledávejte:
GET https://api-globe.appfleece.app/v1/storefront/pickup-points?country=CZ&latitude=…&longitude=…s hlavičkouX-Globe-Publishable-Key. - Zobrazte místa. Když zákazník jedno vybere, vezměte jeho
cart_attributes. - Slučte je se stávajícími atributy košíku a seznam zapište mutací Storefront API
cartAttributesUpdate. - Pokračujte na
checkoutUrl.
Endpointy a kód pro curl, Swift, Kotlin, TypeScript a Hydrogen najdete na stránce Storefront pickup API.
Formát atributů košíku
Sekce “Formát atributů košíku”Po obou možnostech má košík tyto atributy:
| Klíč | Hodnota |
|---|---|
globe_PickupPointId | ID místa |
globe_PickupPointName | Název místa |
globe_PickupPointAddress | Adresa na jednom řádku |
globe_PickupPointData | Celé místo jako řetězec JSON |
globe_DeliveryMethod | pickup |
globe_PickupPointCustomerId | DHL Postnummer, jinak prázdné |
Zapište celé cart_attributes přesně tak, jak je Storefront API pro výdejní místa vrací. Samotné globe_PickupPointId Globe přijme jen jako náhradní řešení, a to jen u sítí dopravců, které si Globe ukládá sám: u dopravců, jejichž místa Globe načítá živě, například GLS nebo DHL, samotné ID ověřit nelze a místo se do objednávky neuloží.
Když zákazník přepne na doručení na adresu, odeberte klíče místa z košíku. Kompletní popis formátu, náhradní řešení jen s ID a to, co se má zapsat při doručení na adresu, najdete na stránce Cart attributes.
Co se děje v pokladně
Sekce “Co se děje v pokladně”Pokladna čte atributy košíku přes přizpůsobení doručení od Globe, pokud jste ho zapnuli v Nastavení → Widget košíku → Přizpůsobení doručení v pokladně:
- Viditelné zůstanou jen dodací sazby dopravce vybraného místa.
- Pokud jste tam nastavili přejmenování sazeb, zobrazí se u sazby název místa.
- Pokud zákazník v pokladně změní zemi doručení na zemi, ve které místo není, pokladna zobrazí všechny sazby jako obvykle.
S hostovanou stránkou pro výběr a se zapnutým Předvyplnění adresy v checkoutu se pokladna navíc otevře s adresou místa jako doručovací adresou. Zákazník ji může změnit. Storefront API pro výdejní místa doručovací adresu nemění.
Co se děje při vytvoření objednávky
Sekce “Co se děje při vytvoření objednávky”Když Shopify vytvoří objednávku, Globe přečte atributy košíku a ověří místo v síti dopravce. To platí pro všechny kanály, včetně widgetu košíku v šabloně.
| Výsledek | Co Globe udělá |
|---|---|
| Místo existuje a je aktivní | Nahradí název, adresu a souřadnice místa údaji dopravce, uloží ho do objednávky (metapole Globe.PickupPoint) a použije tagy, atributy objednávky a poznámku dopravce |
| Místo nebylo nalezeno, není aktivní, je z jiné země, patří dopravci, který není namapovaný na dopravní metodu objednávky, nebo dopravní metoda není sazba s výdejním místem | Neuloží žádné místo. Objednávka dostane tag Chybějící výdejní místo (výchozí point_unselected), pokud ho máte nastavený, a platí obvyklý postup s připomínkami |
| Dopravce není dostupný | Ponechá místo z globe_PickupPointData košíku tak, jak je |
Košík měl jen globe_PickupPointId a Globe ho nedokázal ověřit (u dopravců, jejichž místa Globe načítá živě, například GLS nebo DHL, je to tak vždy) | Neuloží žádné místo a použije tag pro chybějící místo |
Štítky, exporty a integrace ERP nebo WMS vidí stejná pole jako u objednávek z vašeho online obchodu. Viz Metafield pro výdejní místo.
Řešení problémů
Sekce “Řešení problémů”Stránka hlásí „Výběr výdejního místa není pro tento obchod zapnutý.“ Zapněte stránku v Nastavení → Headless a mobilní aplikace. Pokud se v této sekci zobrazuje jen Požádat o přístup, headless výběr pro váš obchod ještě není zapnutý. Napište nám do chatu podpory.
Storefront API pro výdejní místa odpovídá 403 access_required se zprávou „Headless pickup is not enabled for this shop.“
Funkci zapínáme pro každý obchod zvlášť. Napište nám do chatu podpory. Klíč vytvořený dříve začne fungovat, jakmile funkci zapneme.
Stránka hlásí „Tento košík už neexistuje.“ Platnost košíku vypršela, košík už byl převeden na objednávku, nebo patří jinému obchodu. Vytvořte nový košík a otevřete stránku znovu.
Stránka hlásí „Tato návratová adresa není pro obchod povolená.“
return_url nezačíná žádnou z vašich návratových adres. Zkontrolujte schéma, doménu a cestu. Subdomény se za shodu nepovažují.
Stránka hlásí „Výběr výdejního místa je dočasně nedostupný.“ Globe nemá aktivní tarif, nebo nebyla schválena oprávnění ke košíkům obchodu. Otevřete Globe ze Shopify administrace.
Stránka vyžaduje heslo. Online obchod je chráněný heslem, jako je tomu u vývojových obchodů. Zadejte heslo obchodu jednou ve stejném WebView nebo prohlížeči.
Objednávka nemá výdejní místo.
Podívejte se, jestli tagy objednávky obsahují váš tag pro chybějící místo. Pak ověřte, že košík měl před pokladnou globe_PickupPointData, že zákazník zvolil sazbu s výdejním místem téhož dopravce a že země doručení odpovídá zemi místa.
API odpovídá 403 origin_not_allowed.
Přidejte doménu webu do seznamu Povolené webové domény, nebo odeberte všechny domény, aby klíč mohl použít jakýkoli web.
API odpovídá 429 rate_limited pro všechny zákazníky.
Váš server volá API za všechny zákazníky z jedné IP adresy. Volejte ho místo toho ze zařízení nebo prohlížeče zákazníka. Viz Rate limits.
Pokladna zobrazuje sazby s výdejními místy jiných dopravců.
Zapněte Přizpůsobení doručení v pokladně v Nastavení → Widget košíku a ujistěte se, že košík má globe_PickupPointData, ne jen ID.