Sign in with Shop
Use the Shop SDK login feature to add Sign in with Shop to your self-hosted login page. The SDK loads the sign-in code, creates a login instance, and returns an element that you can mount where the sign-in experience should appear.
The Shop platform is in early access. Features and APIs might change before general availability.
The Shop platform is in early access. Features and APIs might change before general availability.
Anchor to What you'll learnWhat you'll learn
In this guide, you'll learn how to:
- Initialize the Shop SDK.
- Create a
loginfeature instance and add it to your page. - Handle authentication events after the user signs in.
Anchor to RequirementsRequirements
- A Shop app with a client ID.
- A storefront where you can add HTML and JavaScript.
Anchor to Step 1: Load and initialize the SDKStep 1: Load and initialize the SDK
Add the SDK loader script to your page and initialize it with your client ID. If you want to preload the login code before calling sdk.create(), set features.login to true.
HTML
The script registers window.ShopSDK when it loads. initialize returns an SDK instance that you use to create the login feature.
Anchor to Step 2: Create a login instanceStep 2: Create a login instance
Call sdk.create('login', config) to create a login instance. The method returns a Promise that resolves after the feature is loaded and the element is ready.
Use the builder to customize the generated SDK code for your login button:
Add a container to your page, such as <div id="login-container"></div>. The SDK creates the underlying HTML element for you. You're responsible for inserting login.element into the DOM wherever you want the sign-in experience to appear.
Anchor to Login attributesLogin attributes
The following attributes are common for the login feature. Pass them as JavaScript configuration in sdk.create(), not as markup on the page.
| Attribute | Description |
|---|---|
buttonType | Changes the call-to-action text. For example, use 'continue' to show a Continue with Shop flow. |
buttonLayout | Renders a standalone button flow when set to 'standalone'. |
emailInputSelector | Connects the login flow to an existing email input instead of rendering a standalone button. |
scope | Required Shop OAuth scope. Use 'shop_app:oauth' to access the user's email. |
appearance.variables | CSS custom properties that customize the rendered login feature. |
For the full list of attributes and event handlers, see the login reference.
Anchor to Step 3: Handle authentication resultsStep 3: Handle authentication results
The onComplete handler runs after the sign-in flow completes. Use it to update your UI or send the authentication result to your backend. If the event includes user-scoped credentials, then handle them like other authentication tokens:
- Send them only over HTTPS.
- If your app needs them after the page session, then store them server-side.
- Don't log them in analytics or error reports.
The onError handler runs when the login flow can't complete. Use it to show a fallback login path or ask the user to try again.
Anchor to Next stepsNext steps
- Review the full
loginfeature reference. - If your sign-in flow returns a
shopConsentToken, then exchange it for a user access token to read and write Shop User data. See Store metafields on Shop users. - Use the lead capture feature to collect email addresses from users who aren't yet signed in.