Skip to main content

Recognize returning Shop users

Use the Shop SDK to detect returning Shop users as soon as they land on your storefront. The onRecognized event fires automatically after SDK initialization, with no user interaction required. You can use the result to personalize content, pre-fill an email input, or surface a targeted sign-in prompt for users who are already known.

Developer preview

The Shop platform is in early access. Features and APIs may change before general availability.

Anchor to What you'll learnWhat you'll learn

In this guide, you'll learn how to do the following tasks:

  • Initialize the Shop SDK with a recognition event handler.
  • Use the recognized state to conditionally update your storefront UI.

Anchor to RequirementsRequirements

  • A Shop app with a client ID.
  • A storefront where you can add HTML and JavaScript.

Anchor to Step 1: Initialize the SDK with ,[object Object]Step 1: Initialize the SDK with onRecognized

Add the SDK loader and pass onRecognized as a top-level option when you call initialize. The handler fires once per page load with the visitor's current recognition state.

HTML

<script type="module">
import 'https://cdn.shopify.com/shopifycloud/shop-js/modules/v2/loader.sdk.esm.js';

const sdk = window.ShopSDK.initialize({
apiKey: 'YOUR_CLIENT_ID',
locale: 'en',
onRecognized(state) {
if (state.recognized) {
// The visitor is a known Shop user on this device
showReturningUserPrompt();
}
},
});
</script>

The onRecognized handler receives a state object with a single recognized boolean. When true, the visitor is a known Shop user on this device. When false, they weren't recognized.

Anchor to Step 2: Update the UI based on recognition stateStep 2: Update the UI based on recognition state

Use the recognized flag to branch your UI. Common patterns include showing a personalized greeting, surfacing a sign-in prompt, or pre-filling an email field.

JavaScript

function showReturningUserPrompt() {
const prompt = document.querySelector('#sign-in-prompt');
if (prompt) {
prompt.textContent = 'Welcome back! Sign in with Shop to continue.';
prompt.hidden = false;
}
}

Because onRecognized fires silently before any user interaction, it's suited for lightweight personalization: updating copy or showing a targeted prompt. Avoid triggering modal dialogs or authentication flows without a user gesture.

Anchor to Next stepsNext steps

  • Add a Sign in with Shop button so recognized users can authenticate with one tap.
  • Use the lead capture component to collect email addresses from visitors who aren't yet recognized.
Was this page helpful?