Shop SDK lead capture now supports Rich Authorization Requests

You can now request the specific profile data your app needs during Shop SDK lead capture, including details that aren't saved on the user's Shop profile. Use Rich Authorization Requests (RAR) to select which fields are required and which ones users can skip. Existing integrations don't need changes to continue working; RAR is opt-in.

What changed

Lead capture now accepts an authorizationDetails attribute. The attribute takes a serialized JSON array that lists the fields your app needs and marks each one as required or optional. For example, this request requires a phone number and makes birthdate optional:

const authorizationDetails = JSON.stringify([

{

type: 'urn:shopify:shop_app:data-sharing:v1',

datatypes: [

{name: 'phone_number', required: true},

{name: 'birthdate', required: false},

]);

const authorizationDetails = JSON.stringify([
  {
    type: 'urn:shopify:shop_app:data-sharing:v1',
    datatypes: [
      {name: 'phone_number', required: true},
      {name: 'birthdate', required: false},
    ],
  },
]);

You can request given name, family name, phone number, and birthdate with RAR. The existing OAuth scopes shop_app:user:profile and shop_app:user:phone let you request existing names and phone numbers, respectively, but don't prompt users to provide missing values.

Before a user authorizes your app, Shop asks them for any requested fields that they haven't shared with your app. Users must provide values for required fields and can skip optional ones. If a user declines to authorize your app, then onComplete doesn't include a shopConsentToken, even if the user signs in to the store. Handle a missing shopConsentToken as an expected outcome.

Who's affected

This change applies to apps that use Shop SDK lead capture. To read data that you request with RAR, your app needs a client secret and a trusted server.

As with existing lead capture, an authorized phone number returned by Shop can replace a different phone number on the store's customer record. Existing names aren't replaced.

What to do

To request data with RAR:

Pass your serialized array as attributes.authorizationDetails when you create the lead capture instance. To also request the user's identifier and email, set attributes.scope to 'shop_app:oauth', as shown in the guide.
In onComplete, send shopConsentToken to your server when the event includes one. The event doesn't include the requested data. If the event includes customerUpdateErrors, then the update to the store's customer record failed.
From your server, exchange the consent token with the fetchTokensForUser mutation on the Shop Partners API. Read the authorized fields from the response or from the Shop Users API, and handle null for fields that weren't granted or have no value.
Before you ship, test a completed authorization, a skipped optional field, a declined authorization, and a request with malformed authorizationDetails JSON that returns invalid_authorization_details in onError. For the request format and error handling, see the lead capture guide.

Related docs

Was this page helpful?