Skip to main content

Manifest

Learn how to configure your Shop Mini using the manifest.json file. The manifest defines critical properties like description, permissions, scopes, and trusted domains.

Anchor to OverviewOverview

Every Shop Mini requires a manifest.json file in the src folder of the project. This file defines the configuration and capabilities of your Mini, including what permissions it needs, what user data it can access, and which external domains it can communicate with.

The manifest is validated during the submission process and must be properly configured for your Mini to function correctly.

Anchor to Manifest StructureManifest Structure

Here's an example of a complete manifest.json file:

Anchor to PermissionsPermissions

The permissions field is an array that specifies which native device capabilities your Mini requires. These permissions are requested from the user when your Mini attempts to use them.

Anchor to Available PermissionsAvailable Permissions

  • CAMERA - Access to the device camera for taking photos or videos
  • MICROPHONE - Access to the device microphone for audio recording
  • MOTION - Access to device motion sensors (accelerometer, gyroscope)

Anchor to ExampleExample

{
"permissions": ["CAMERA", "MICROPHONE"]
}
Caution

Only request permissions that are essential to your Mini's core functionality. Requesting unnecessary permissions may delay approval during the review process.

Anchor to ScopesScopes

The scopes field is an array that defines what user data your Mini can access through the Shop Minis SDK. Some hooks in the SDK require specific scopes to be declared in the manifest before they can be used.

Anchor to Available ScopesAvailable Scopes

Anchor to User ScopesUser Scopes

  • openid - OpenID Connect authentication. Required for generating user tokens.
  • profile - Read access to user's buyer profile.
  • user_settings:read - Read access to the current user.

Anchor to Product ScopesProduct Scopes

  • products:recent:read - Read access to the user's recently viewed products.
  • products:recommendations:read - Read access to personalized product recommendations for the user.

Anchor to Shop ScopesShop Scopes

  • shops:recent:read - Read access to the user's recently viewed shops.
  • shops:follows:read - Read access to shops the user follows.
  • shops:follows:write - Write access to follow or unfollow shops.
  • shops:recommendations:read - Read access to personalized shop recommendations for the user.

Anchor to Order ScopesOrder Scopes

  • orders - Access to the user's order history and details.

Anchor to Product List ScopesProduct List Scopes

  • product_list:read - Read access to the user's collections (favorites, wishlists, etc.).
  • product_list:write - Write access to create, update, or delete collections.
  • product_list_item:write - Write access to add or remove items from collections.

Anchor to ExampleExample

{
"scopes": ["profile", "orders"]
}
Note

Always follow the principle of least privilege - only request scopes that are necessary for your Mini's functionality. Review the Guidelines for more information on data privacy requirements.

Anchor to Trusted DomainsTrusted Domains

The trusted_domains field is an array of domains that your Mini is allowed to communicate with. This is a critical security feature that restricts network requests to approved domains only.

Anchor to UsageUsage

Trusted domains are required for:

  • Network requests - Any fetch() calls to external APIs
  • Image sources - Loading images from external URLs
  • Video sources - Loading videos from external URLs
  • Other external resources - Any content loaded from outside your Mini's bundle

Anchor to Domain FormatDomain Format

  • Do not include the protocol (e.g., https://)
  • You can include paths to be more specific
  • Subdomains must be listed separately
  • Do not include trailing slashes
  • Be as specific as possible - For example, if using Google Cloud Storage, include the full path to your specific bucket rather than just the domain

Anchor to ExampleExample

{
"trusted_domains": [
"api.example.com/v1",
"storage.googleapis.com/my-mini-bucket",
"cdn.example.com/assets"
]
}
Caution

Your Mini will not be able to make requests to any domain not listed in this array. Make sure to include all domains you need before submitting your Mini for review.

Tip

Be as specific as possible with your paths. Instead of storage.googleapis.com, use storage.googleapis.com/my-mini-bucket to limit access to only your bucket.

Anchor to HandleHandle

The handle field is a unique identifier for your Mini. This value is automatically assigned when you create your Mini through the Shop Minis platform.

Anchor to CharacteristicsCharacteristics

  • Automatically generated during Mini creation
  • Must be unique across all Shop Minis
  • Used internally by Shop to identify your Mini
  • Cannot be changed after initial assignment
  • Used to deeplink into your Mini (shop.app/mini/my-mini-handle)

Anchor to ExampleExample

{
"handle": "my-awesome-mini"
}
Note

You typically don't need to manually set this field. It's automatically populated when you initialize a new Mini project using the Shop Minis CLI.

Anchor to DescriptionDescription

The description field provides a brief summary of your Mini's purpose and functionality. This description is displayed to users in various places within the Shop app to help them understand what your Mini offers.

Anchor to CharacteristicsCharacteristics

  • Should be concise and informative (recommended 30-50 characters)
  • Helps users discover and understand your Mini's value proposition
  • Used in search results and Mini details

Anchor to ExampleExample

{
"description": "Track your outfits every day"
}

Anchor to Best PracticesBest Practices

  • Be specific: Clearly state what unique value your Mini provides
  • Keep it concise: Aim for 30-50 characters maximum
  • Use action words: Start with verbs like "Discover," "Shop," "Track," or "Explore"
  • Highlight key features: Mention the main benefit or differentiator of your Mini

Anchor to Best PracticesBest Practices

Anchor to Minimize Permissions and ScopesMinimize Permissions and Scopes

Only request the permissions and scopes that are absolutely necessary for your Mini's core functionality. This improves user trust and speeds up the review process.

Anchor to Keep Trusted Domains UpdatedKeep Trusted Domains Updated

As your Mini evolves, make sure to update the trusted_domains list if you add new external services or APIs. Missing domains will cause runtime errors.

Anchor to ValidationValidation

Test your manifest configuration thoroughly during development to catch any issues before submission. The Shop Minis SDK will validate your manifest and provide warnings for common issues.

Was this page helpful?