Punkty odbioru w sklepach headless i aplikacjach mobilnych
Widżet koszyka Globe działa w motywie Shopify. Natywna aplikacja mobilna zbudowana na Storefront API albo sklep headless, na przykład na Hydrogen lub Next.js, nie ma motywu, w którym można by go umieścić. Ten przewodnik pokazuje, jak kupujący w takich aplikacjach wybierają punkt odbioru, zanim dotrą do kasy Shopify.
Obie opcje opisane poniżej zapisują punkt w koszyku Storefront API jako atrybuty koszyka. Od tego momentu kasa i przetwarzanie zamówienia traktują punkt dokładnie tak samo jak punkt wybrany w widżecie koszyka.
Wybierz opcję
Dział zatytułowany „Wybierz opcję”| A: hostowana strona wyboru | B: Storefront API punktów odbioru | |
|---|---|---|
| Co budujesz | Otwierasz adres URL w WebView, oknie popup lub iframe | Własną mapę lub listę w interfejsie swojej aplikacji |
| Interfejs | Mapa, lista, wyszukiwarka, geolokalizacja i filtr przewoźników Globe | Twój własny |
| Kto zapisuje koszyk | Globe | Twoja aplikacja, przez cartAttributesUpdate |
| Dane uwierzytelniające | Brak. Strona działa w domenie Twojego sklepu | Klucz publiczny (glb_pk_…) |
| Czym zajmuje się Twoja aplikacja | Otwarciem strony i odczytaniem wyniku | Lokalizacją, wyszukiwaniem, listą punktów i zapisem koszyka |
Zacznij od opcji A, jeśli chcesz szybko mieć działające rozwiązanie. Wybierz B, gdy selektor ma wyglądać i działać natywnie. Później możesz przejść na drugą opcję: obie zapisują te same atrybuty koszyka.
Zanim zaczniesz
Dział zatytułowany „Zanim zaczniesz”- Globe jest zainstalowany i ma aktywny plan.
- Wybór punktu w trybie headless jest włączony dla Twojego sklepu. Włączamy go dla każdego sklepu osobno: napisz do nas na czacie wsparcia w aplikacji. Do tego czasu sekcja Ustawienia → Aplikacje headless i mobilne pokazuje tylko przycisk Poproś o dostęp, a strona wyboru i Storefront API punktów odbioru odpowiadają, że funkcja nie jest włączona.
- Co najmniej jeden przewoźnik z punktami odbioru jest skonfigurowany i przypisany do metod wysyłki. Zobacz Dodawanie przewoźników z punktami odbioru.
- Twoja aplikacja tworzy koszyki przez Storefront API i kieruje kupujących na
checkoutUrlkoszyka.
Konfiguracja Globe
Dział zatytułowany „Konfiguracja Globe”W panelu Globe przejdź do Ustawienia → Aplikacje headless i mobilne.
Hostowana strona wyboru
Dział zatytułowany „Hostowana strona wyboru”- W sekcji Strona wyboru punktu odbioru kliknij Włącz.
- W sekcji Adresy powrotu kliknij Dodaj adres powrotu i dodaj każdy adres, na który strona może odesłać kupujących:
- deep link aplikacji, na przykład
myapp://pickup, - universal link lub Android App Link, na przykład
https://app.example.com/pickup, - adres internetowy Twojego sklepu headless, na przykład
https://shop.example.com/cart.
- deep link aplikacji, na przykład
- Kliknij Zapisz na pasku zapisu.
Adresy powrotu są opcjonalne, jeśli Twoja aplikacja odczytuje wynik wyłącznie przez natywny most lub postMessage. Są wymagane przy przekierowaniach, a dozwolone źródła dla postMessage pochodzą z adresów powrotu https. Zobacz Adresy powrotu.
Jeśli karta informuje, że Globe potrzebuje uprawnień do koszyka sklepu, otwórz raz Globe z panelu administracyjnego Shopify i zatwierdź zaktualizowane uprawnienia. Do tego czasu strona pokazuje, że wybór jest niedostępny.
Storefront API punktów odbioru
Dział zatytułowany „Storefront API punktów odbioru”- W sekcji Storefront API punktów odbioru kliknij Utwórz klucz i skopiuj klucz publiczny.
- Opcjonalnie: w sekcji Dozwolone źródła internetowe kliknij Dodaj źródło i dodaj źródła (origins) swojego sklepu internetowego, na przykład
https://shop.example.com. Bez żadnych źródeł na liście klucza może używać każda strona internetowa. Aplikacji natywnych to nie dotyczy. - Kliknij Zapisz na pasku zapisu.
Klucz publiczny służy tylko do wyszukiwania punktów odbioru Twoich przewoźników, dlatego można go bezpiecznie umieścić w aplikacji lub w kodzie uruchamianym w przeglądarce. Zobacz Uwierzytelnianie.
Opcja A: hostowana strona wyboru
Dział zatytułowany „Opcja A: hostowana strona wyboru”-
Utwórz lub wczytaj koszyk kupującego przez Storefront API i zachowaj jego
id. -
Otwórz ten adres URL w domenie swojego sklepu:
https://{shop domain}/apps/appfleece-globe/select?cart={URL-encoded cart id}&return_url={allowlisted URL}&state={your value} -
Kupujący wybiera punkt. Globe weryfikuje go u przewoźnika i zapisuje atrybuty koszyka.
-
Twoja aplikacja otrzymuje wynik: przekierowanie na
return_url, wiadomość przez natywny most albopostMessage. -
Pobierz koszyk ponownie i przejdź do
checkoutUrl.
Pełną listę parametrów, komunikaty wyniku i kod dla iOS, Androida, React Native i Hydrogen znajdziesz na stronie Hosted selection page.
Opcja B: Storefront API punktów odbioru
Dział zatytułowany „Opcja B: Storefront API punktów odbioru”- Poproś kupującego o lokalizację albo pozwól mu przesuwać mapę.
- Wyszukaj:
GET https://api-globe.appfleece.app/v1/storefront/pickup-points?country=CZ&latitude=…&longitude=…z nagłówkiemX-Globe-Publishable-Key. - Wyświetl punkty. Gdy kupujący wybierze jeden z nich, pobierz jego
cart_attributes. - Scal je z istniejącymi atrybutami koszyka i zapisz listę mutacją Storefront API
cartAttributesUpdate. - Przejdź do
checkoutUrl.
Endpointy i kod dla curl, Swift, Kotlin, TypeScript i Hydrogen znajdziesz na stronie Storefront pickup API.
Kontrakt atrybutów koszyka
Dział zatytułowany „Kontrakt atrybutów koszyka”Obie opcje kończą się tymi atrybutami w koszyku:
| Klucz | Wartość |
|---|---|
globe_PickupPointId | ID punktu |
globe_PickupPointName | Nazwa punktu |
globe_PickupPointAddress | Adres w jednej linii |
globe_PickupPointData | Pełne dane punktu jako ciąg JSON |
globe_DeliveryMethod | pickup |
globe_PickupPointCustomerId | Postnummer DHL, w przeciwnym razie puste |
Zapisz pełne cart_attributes dokładnie w takiej postaci, w jakiej zwraca je Storefront API punktów odbioru. Globe akceptuje samo globe_PickupPointId tylko awaryjnie i tylko dla sieci przewoźników, które Globe przechowuje u siebie. U przewoźników, których Globe odpytuje na żywo, na przykład GLS lub DHL, samego ID nie da się zweryfikować i punkt nie zostanie zapisany w zamówieniu.
Gdy kupujący przełączy się na dostawę do domu, usuń klucze punktu z koszyka. Na stronie Cart attributes znajdziesz pełny kontrakt, tryb awaryjny z samym ID oraz informacje o tym, co zapisać przy dostawie do domu.
Co dzieje się w kasie
Dział zatytułowany „Co dzieje się w kasie”Kasa odczytuje atrybuty koszyka przez dostosowanie dostawy Globe, jeśli jest ono włączone w Ustawienia → Widget koszyka → Dostosowanie dostawy w kasie:
- Widoczne pozostają tylko stawki wysyłki przewoźnika wybranego punktu.
- Jeśli skonfigurujesz tam zmianę nazw stawek, stawka pokazuje nazwę punktu.
- Jeśli kupujący zmieni w kasie kraj dostawy na taki, w którym punkt się nie znajduje, kasa pokazuje wszystkie stawki jak zwykle.
Przy hostowanej stronie wyboru i włączonej opcji Automatyczne wypełnianie adresu w kasie kasa otwiera się również z adresem punktu jako adresem dostawy. Kupujący nadal może go zmienić. Storefront API punktów odbioru nie zmienia adresu dostawy.
Co dzieje się po utworzeniu zamówienia
Dział zatytułowany „Co dzieje się po utworzeniu zamówienia”Gdy Shopify tworzy zamówienie, Globe odczytuje atrybuty koszyka i weryfikuje punkt w sieci przewoźnika. Dotyczy to każdego kanału, łącznie z widżetem koszyka w motywie.
| Wynik | Co robi Globe |
|---|---|
| Punkt istnieje i jest aktywny | Zastępuje nazwę, adres i współrzędne punktu danymi przewoźnika, zapisuje punkt w zamówieniu (metafield Globe.PickupPoint) i stosuje tagi, atrybuty zamówienia i notatkę przewoźnika |
| Punkt nie został znaleziony, jest nieaktywny, znajduje się w innym kraju, należy do przewoźnika nieprzypisanego do metody wysyłki zamówienia albo metoda wysyłki nie jest stawką do punktu odbioru | Nie zapisuje punktu. Zamówienie otrzymuje tag Brak punktu odbioru (domyślnie point_unselected), jeśli go ustawisz, i działa zwykły proces przypomnień |
| Nie można połączyć się z przewoźnikiem | Zachowuje punkt z globe_PickupPointData koszyka bez zmian |
Koszyk miał tylko globe_PickupPointId i Globe nie mógł go zweryfikować (zawsze u przewoźników, których Globe odpytuje na żywo, na przykład GLS lub DHL) | Nie zapisuje punktu i stosuje tag braku punktu |
Etykiety, eksporty oraz integracje ERP i WMS widzą te same pola co w zamówieniach z Twojego sklepu internetowego. Zobacz Metafield punktu odbioru.
Rozwiązywanie problemów
Dział zatytułowany „Rozwiązywanie problemów”Strona pokazuje komunikat „Wybór punktu odbioru nie jest włączony w tym sklepie.” Włącz stronę w Ustawienia → Aplikacje headless i mobilne. Jeśli ta sekcja pokazuje tylko Poproś o dostęp, wybór punktu w trybie headless nie jest jeszcze włączony dla Twojego sklepu. Napisz do nas na czacie wsparcia.
Storefront API punktów odbioru odpowiada 403 access_required z komunikatem „Headless pickup is not enabled for this shop.”
Funkcja jest włączana dla każdego sklepu osobno. Napisz do nas na czacie wsparcia. Klucz utworzony wcześniej zacznie działać, gdy tylko funkcja zostanie włączona.
Strona pokazuje komunikat „Ten koszyk już nie istnieje.” Koszyk wygasł, został już zamieniony w zamówienie albo należy do innego sklepu. Utwórz nowy koszyk i otwórz stronę ponownie.
Strona pokazuje komunikat „Ten adres powrotu nie jest dozwolony dla tego sklepu.”
return_url nie zaczyna się od żadnego z Twoich adresów powrotu. Sprawdź schemat, host i ścieżkę. Subdomeny nie są dopasowywane.
Strona pokazuje komunikat „Wybór punktu odbioru jest chwilowo niedostępny.” Globe nie ma aktywnego planu albo uprawnienia do koszyka sklepu nie zostały zatwierdzone. Otwórz Globe z panelu administracyjnego Shopify.
Strona prosi o hasło. Sklep internetowy jest chroniony hasłem, tak jak sklepy deweloperskie. Wprowadź raz hasło do sklepu w tym samym WebView lub w tej samej przeglądarce.
Zamówienie nie ma punktu odbioru.
Sprawdź, czy wśród tagów zamówienia jest Twój tag braku punktu. Następnie sprawdź, czy koszyk miał globe_PickupPointData przed przejściem do kasy, czy kupujący wybrał stawkę do punktu odbioru tego samego przewoźnika i czy kraj dostawy zgadza się z krajem punktu.
API odpowiada 403 origin_not_allowed.
Dodaj źródło strony internetowej w sekcji Dozwolone źródła internetowe albo usuń wszystkie źródła, aby dopuścić każdą stronę.
API odpowiada 429 rate_limited dla każdego kupującego.
Twój serwer wywołuje API dla wszystkich kupujących z jednego adresu IP. Wywołuj je zamiast tego z urządzenia lub przeglądarki kupującego. Zobacz Limity zapytań.
Kasa pokazuje stawki do punktów odbioru innych przewoźników.
Włącz Dostosowanie dostawy w kasie w Ustawienia → Widget koszyka i upewnij się, że koszyk ma globe_PickupPointData, a nie tylko ID.