Platform Connection
Platform connection is the term used for when a platform is connected to SparkLayer. There are two endpoints that are used to inform of a new connection or once it's removed. It is also important to understand and support the two different flows for a new platform connection, depending on how the platform is connected to SparkLayer.
There are two different flows for a new platform connection, depending on how the platform is connected to SparkLayer:
This is when the platform connection is initialised though the relevant app store (or similar) on the eCommerce platform. For example, this is when a merchant installs the SparkLayer app on BigCommerce or Shopify.
Please note: this flow is only applicable if the Ignite integration is being built for a platform that supports 3rd party apps.
Dashboard API: The SparkLayer Dashboard API is used to register the user with SparkLayer, create a platform connection between a 3rd party platform and a SparkLayer site, and to obtain the site onboarding progress data. The documentation for this API is not available publicly, but can be provided on request.
The flow is as follows:
- The eCommerce platform SparkLayer app is installed on the store
- Store credentials and other relevant data required by the integration should be stored in the integration for later use. This usually includes the store identifier and eCommerce platform API access token or credentials.
- The user is shown a SparkLayer registration page within the now installed platform SparkLayer app. To regsiter the user with SparkLayer, the internal SparkLayer Dashboard API user registration endpoint should be called.
- Once the registration is successful, SparkLayer will return the relevant site environment and ID values which should then be used to call the SparkLayer site platform connection endpoint telling SparkLayer that we want to link the eCommerce platform to the newly registered SparkLayer site.
- SparkLayer will then call the Ignite integration New Platform Connection endpoint with the SparkLayer site id and credentials data, and the Ignite integration should store this and perform the complete platform connection actions such as full data sync.
- At this stage, the platform connection is complete and the user on the eCommerce platform store app (if applicable) should be shown the SparkLayer onboarding steps as well as links to the SparkLayer Dashboard and end-user documentation (the onboarding progress data can be obtained though the SparkLayer Dashboard API's GET onboarding steps endpoint).
This is when the platform connection is initialised though the SparkLayer Dashboard Configuration -> Integrations -> eCommerce Platform page of an existing SparkLayer site. In this scenario the flow is as follows:
- SparkLayer will call the Ignite integration's new platform connection endpoint with the SparkLayer site and credentials data.
- The integration should store this data and return a redirect url to which the merchant user should be redirected to install the SparkLayer app on the eCommerce platform.
- Once the app is installed, the eCommerce store credentials and other relevant data should be stored in the integration.
- As at this point both the SparkLayer and the eCommerce platform data is known by the integration, the platform connection is complete, and actions such as a full data sync can be initialised.
- The user can be shown the SparkLayer onboarding steps and progress (the onboarding progress data can be obtained though the SparkLayer Dashboard API's GET onboarding steps endpoint).
Dashboard API: The SparkLayer Dashboard API is used to register the user with SparkLayer, create a platform connection between a 3rd party platform and a SparkLayer site, and to obtain the site onboarding progress data. The documentation for this API is not available publicly, but can be provided on request.
These endpoints are used by SparkLayer to inform the integration of a new platform connection or when it's removed.
The integration should record the new platform connection and perform the inital actions if connection is complete.
If the endpoint is called by the SparkLayer Dashboard platform connect flow, this endpoint should return a redirect_url parameter which will be used by the SparkLayer dashboard to redirect the user to the platform SparkLayer app installation page.
Finally, once the platform connection is complete (both SparkLayer and platform config and credentials are known and the integration is able to start syncing data), the following actions should be performed:
- Register any data change webhooks with the platform if available.
- Sync the store settings from the platform to the Spark API.
- Start a full synchronisation of customers and product data.
Important considerations:
- Please note that the completion of the platform connection may not coincide with the call to the Add Platform Connection endpoint. This is true when the connection is initiated through the SparkLayer Dashboard and is pending completion on the external platform. In such cases, the endpoint should return a redirect_url for redirecting the user to the platform's SparkLayer installation page where the merchant can complete the process linking their store to the pending platform connection.
- The endpoint should be idempotent - if the platform connection is already established the endpoint should re-triger the connection completion actions in a safe idempotent way.
This endpoint performs the following actions:
- Stop any processing of any syncing
- Delete store sync logs
- Delete any connection data locally
Our API uses OAuth access tokens and therefore shortlived access tokens are required to be created. These should be stored locally alongside the connection data and refreshed when required.