Skip to main content
Smile has introduced a new JavaScript SDK method called SmileUI.initialize() which is intended to replace the SmileUI.init() method (which is now deprecated). This article explains everything you need to know about the differences between them, who is impacted by this change, and how to migrate from the old to the new method.
Feature availability: SmileUI.initialize() is available on Plus and Enterprise plans.
Warning: The deprecated SmileUI.init() method will stop working after January 31, 2026. Please ensure you complete the migration before this date.

​
Differences between init() and initialize()

Fundamentally, the only difference between the SmileUI.init() and SmileUI.initialize() methods is their arguments. Both accept an options hash (as described in our developer documentation), however the keys of the options hash have changed. Besides the new keys and their values, the behaviour of the two methods is identical.
Old Options KeyNew Options KeyNew Value
channel_keypublishableKeyThe account’s publishable key.
customer_identity_jwtcustomerTokenA JWT signed using one of the account’s signing keys. Full instructions on JWT generation can be found here.
Tip: Previously, you would use an account’s Private Key to sign the JWT passed in as the customer_identity_jwt. However with the new initialize() method and the customerToken argument, the JWT has a different format and must be signed with one of the account’s signing key. Be sure not to mix these up!

​
How to determine where migration is needed

For your standard Shopify or BigCommerce storefront, no migration is needed. However, surfaces that will require migration are:
  • Anywhere (besides your Shopify or BigCommerce storefront) where you’ve manually added Smile’s rewards popup (launcher & panel) — such as on a custom storefront or another website.
  • Anywhere you’ve manually included Smile’s JavaScript SDK — such as a custom checkout, landing page, or any other webpage.
  • Anywhere you’re using Smile’s legacy integration with an e-commerce platform other than Shopify or BigCommerce (e.g. are using Storefront.js).
In short, for anywhere that you’ve ever followed the instructions here, you’ll need to migrate.

​
Migrating from init() to initialize()

Important: If you’re currently using Storefront.js, refer to our guide for migrating from Storefront.js to Smile.js instead.
Pre-requisites: Before completing this guide, you’ll need to ensure the following.
  • Your account is on a plan that includes JavaScript SDK access. The easiest way to confirm this is in Smile Admin, going to Settings > Developer Tools. If you see a card to Manage signing keys and there is a button to generate a new signing key, then you have access!
  • You have a full and complete list of any frontends where you’ve manually included Smile UI / Smile.js / Smile’s JavaScript SDK (see above).
Migration steps: For each of the places/websites (“web properties”) where you’ve manually included the JavaScript SDK, follow these steps.
  1. In Smile Admin, create a new signing key specifically for the web property.
    1. Choose a name that represents the web property the key will be used on (e.g. “Marketing Website”).
  2. Replace any calls to the old SmileUI.init() method to instead call SmileUI.initialize(), ensuring that you’re using the new keys in the options hash (refer to our developer documentation).
  3. Repeat these steps for every web property where you’ve manually included the JavaScript SDK.
Once you’ve repeated the steps above for every place where you’ve manually included the JavaScript SDK, your migration is complete! January 31, 2026 is the official end-of-life date for the old SmileUI.init() method, so you’ll need to ensure that you’ve migrated before that date or your code will stop working.