Test your integration

This article provides guidance on testing your integration as a Buy provider within Ledger Live. This is the final step before deploying your Buy widget to Ledger Live’s production environment.

3 different flows must be tested on all devices, including desktop, iOS, and Android:

1. New user flow (registration)
2. Returning user flow (login)
3. “Buy again” flow (after you’ve already initiated a purchase, a “Buy again with” button is displayed in the initial Buy screen in Ledger Live)

Additionally, certain UX requirements mentioned later in this article, which are shared across all 3 flows, need also to be respected.

Prerequisites for testing

• Technical integration: you should have completed all the steps outlined earlier in this guide (Backend, LiveApp).
• Accounts in Ledger Live: to initialize and complete a purchase, you need accounts in Ledger Live (like Bitcoin or Ethereum). Setting up these accounts in Ledger Live requires owning a Ledger hardware device.
• Authentication and payment methods: you need to use your own verified accounts (KYC) for logging in, and your own payment methods to conduct real transactions in your widget in Ledger Live.

How to test

Testing on your own environment

When building your LiveApp, testing in different environments can be useful for checking how it performs inside Ledger Live. Ledger Live uses a “manifest” (a JSON configuration file) to load embedded LiveApps with specific parameters.

We designed two attributes that can be set in this file, allowing you to switch environments for your widget (e.g., testing on your localhost or staging environment):

• providerTestId: This parameter specifies to Ledger Live which provider you want to test. Once this is set, when you navigate to the buy-sell tab, only the specified provider will appear in the list of supported providers. If you don’t know your provider ID, please contact Ledger.
• providerTestBaseUrl: This parameter allows you to set the base URL of your environment (e.g., http://localhost:3000/buy, https://provider.staging).

Once these two parameters are added, the base URL of your LiveApp loaded in Ledger Live will be replaced by the providerTestBaseUrl you’ve specified, allowing you to test your LiveApp in the environment of your choice.

Example:

• Original LiveApp’s URL loaded in Ledger Live:

https://yourwidget.com?[accountAddress]=x0…&[cryptoCurrency]=bitcoin&[fiatCurrency]=EUR&[fiatAmount]=50&[cryptoAmount]=0.0009490481&[mode]=buy&[paymentMethod]=bank&[bankResidency]=fr&[buySessionId]=cd12538-b02a-4282-99de-4d90f10769a0&[language]=en&[theme]=dark&[platform]=desktop

• After loading the buy-sell-ui manifest locally with the two testing parameters ("providerTestId", "providerTestBaseUrl"), the new LiveApp’s URL that will be loaded in Ledger Live for your provider will be:

http://providerTestBaseUrl?[accountAddress]=x0…&[cryptoCurrency]=bitcoin&[fiatCurrency]=EUR&[fiatAmount]=50&[cryptoAmount]=0.0009490481&[mode]=buy&[paymentMethod]=bank&[bankResidency]=fr&[buySessionId]=cd12538-b02a-4282-99de-4d90f10769a0&[language]=en&[theme]=dark&[platform]=desktop

The environment you set for testing will need to accept query string parameters generated by Ledger Live for your widget. You will not be able to modify them using providerTestBaseUrl because some of these parameters are generated by Ledger Live’s backend. This allows you to test the real use case in your local environment.

Step-by-step instructions:

1. Ledger will provide you with the manifest to load in Ledger Live to connect the Buy/Sell section to a specific environment. Before loading the manifest into Ledger Live, you will need to add the parameters described above ("providerTestId", "providerTestBaseUrl").
   Instructions on how to load a manifest can be found here, under the “Add a local app” paragraph.
2. Once the manifest is added, go to the Buy/Sell section as usual, and you will only see your provider (that you have specified in the "providerTestId" attribute of the manifest) listed among the available providers.
3. Click on the provider, and the URL you specifed in the "providerTestBaseUrl" attribute of the manifest will be open in Ledger Live.

Pre-production testing

You must also conduct tests in Ledger Live’s pre-production environment, which will use your production keys and production endpoints. This allows your team to test the integration under real-world conditions by conducting real transactions.

As with the process described in the previous section (“Testing on your own environment”), Ledger will provide you with a manifest (JSON file) that you’ll need to load into Ledger Live to connect the “Buy/Sell” section to the pre-production environment. However, unlike testing on your own environment, you must not modify this manifest to ensure the “Buy/Sell” section connects to the pre-production environment and directs users to the real URL of your widget.

What to test

UX requirements

• Non-editable wallet address: when users reach your widget, the wallet address should be shown on a review page before completing the transaction, and it should not be editable.
• Persistent session: users should remain logged in to your widget even after closing and reopening either the widget or Ledger Live.
• Dark/Light mode: your widget should automatically adjust its layout (if available) to match the user’s selected theme in Ledger Live, whether dark or light.
• Automatic payment method selection: the payment method previously chosen in Ledger Live should be automatically selected when users reach your widget.
• Responsive LiveApp: on mobile devices, your widget should be responsive and adjust its layout to fit mobile screens.

Authentication / Account creation

• New account creation: you should complete the full account creation process on your widget within Ledger Live to ensure that no steps in the flow are broken. This includes verifying that all KYC steps can be successfully completed within Ledger Live, using the device’s camera and/or file upload feature.
• Login: you must be able to login/logout into your widget within Ledger Live. The login session must be persistent, to ensure users don’t have to log in every time they open the widget.

Transactions

• Quote accuracy: you need to make sure that the quotes shown in Ledger Live match those displayed in your widget, including all fees.
• Buy transaction: you should perform real transactions using as many of the blockchains supported by your services as possible, along with various FIAT currencies and payment methods. Ensure that transactions are confirmed and that funds are received on the expected Ledger wallet address (on-chain proof).
• Buy again transaction: if you’ve already initiated a purchase in Ledger Live with your provider, a “Buy again with” button will be displayed in the first Buy screen of Ledger Live. You must ensure that the Buy Again flow works as expected.

Next steps

Once you have completed your tests, please share your results with Ledger. We will evaluate the priority of each potential issue and implement fixes accordingly.