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.

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 after initialization with the visitor's current recognition state, and again if that state changes, for example after the visitor signs in on the page.

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, { eligibleForSignInWithShop }) {
if (state.recognized && eligibleForSignInWithShop) {
// The visitor is a known Shop user on this device
showReturningUserPrompt();
}
},
});
</script>

The onRecognized handler receives a state object with a single recognized boolean. It also receives a second context argument whose eligibleForSignInWithShop boolean reports whether the store offers Sign in with Shop, so you can limit a sign-in prompt to stores that offer it. When recognized is true, the visitor is a known Shop user on this device. When recognized is 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 Check Sign in with Shop eligibilityCheck Sign in with Shop eligibility

Use onEligibleForSignInWithShop to check whether the store offers Sign in with Shop. The handler fires once after initialization, and its second argument's userRecognized value reports whether the visitor is a recognized Shop user. You can show a sign-in prompt only when the store offers Sign in with Shop.

JavaScript

const sdk = window.ShopSDK.initialize({
apiKey: 'YOUR_CLIENT_ID',
onEligibleForSignInWithShop(eligible, { userRecognized }) {
if (eligible && !userRecognized) {
showSignInWithShopPrompt();
}
},
});

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?