Embedding our editors into your existing site or another site, in its simplest form is actually pretty straight forward. This articles attempts to provide you with all the tools and understanding that you will need in order at least successfully mimic the process.
Supported Editors: MegaEdit, Infigo Editor
Firstly we recommend viewing the attached resources (see below) as it provides additional information on how the process works along with tools to get setup quickly and start testing.
The first step with all API communication is to obtain your API Token from the Support Team.
Now you have this we can look at the specifics required to load an editor, capture the personalization and then create the artwork or place an order.
This integration essentially allows you, through a number of sequential API calls, to load up one of our editors via an iframe, on an external site.
For this you need to have an Infigo customer (who is making the request), a product (to determine what editor and product to load) and then you request from the API a link to load up the editor. This URL we provide you with you can then embed dynamically within your iframe source and, when clicked, it will log the customer in and load up the relevant editor and product.
The final step is to place an order or create an output, all of which we will cover below.
Pre-requisite: In order overcome the Safari (and potentially more when other browsers follow suit) third party cookie security policy that was introduced we require a sub domain binding and SSL certificate to be configured on your Infigo storefront that is the same domain as the requesting site. Without setting this up prior to carrying out this integration it will cause issues.
1. Get the Customer GUID (Optional)
NOTE: The customer you are using in Infigo must be a REGISTERED user (with the customer role: 'Registered')
The customer GUID is required and so when you are mapping customers from your external system and Infigo you can decide to either map the Infigo customer ID, email address or customer GUID. The first two are readily available in the UI and obviously email address should generally match anyway. The customer GUID however, which is required for the subsequent calls, requires an API call to return it.
Depending on how you intend to implement this integration you can either ensure that all your customers in your external site have a respective customer created in Infigo for them (this usually only really works in a fixed B2B scenario) or you have one 'website' user in your system that is always passed to create the editor and place the orders.
Either way, the customer being used needs to have a mapping entry from Infigo that can be sent with the requests. If you don't store the customer GUID then this call is required.
id as mentioned above can be the Infigo customer ID, the customer email address, or the customer GUID.
The response to this request contains lots of customer data, for this purpose we need to capture the "Guid" (responseJSON.Guid)
2. Get the Editor URL
This API request creates a link to embed the editor into an iframe. This link will automatically authenticate the user and is only valid for a short period of time. It needs to include the Customer Guid and the Product Id.
There are a number of parameters that can be specified in the request:
- id - this is the Customer Guid
- productId OR SKU - this is the Infigo product Id or the product SKU
- errorUrl (optional) - incase of an error during the authentication we can redirect the user
- embeddedOperationMode - When embedding MegaEdit this should always be set to "true" for this purpose. Otherwise this can be removed.
The response is simply a URL that includes a temporary AutoLogin token that should be inserted into your iframe src.
3. Placing an Order or Requesting output
The final step is to get some sort of output generated in Infigo.
There are two options that we recommend here, and the decision on which route to take really depends on your requirements.
a. Place an Order
This leads to an actual order being created in Infigo. This requires far more information to be passed in the request as it needs everything relevant to the order in order for it to be validated (delivery information, billing information, shipping method etc.) This has its benefits though, if an order is created in Infigo then you can report on it and review it in Infigo if you require, you can also then utilise things like Infigo Connect and hot folder and Infigo Sync tools. This is usually beneficial when you want to centralise all your orders in Infigo, potentially from multiple sources.
To do this you use our RecordOrder API:
For more specific information on our RecordOrder API method view our related article
b. Create Output
This is a far simpler request to make, however it will not create an order in Infigo. Instead you simply pass the JobId (that you captured from the editor events) and ask Infigo just to create the output.
In the request you can specific a Hot Folder for it to be downloaded to or a callbackURL which will we then post the file to.
- Postman Collection (API Embedded editor Collection.json) - Download this and then import it into your Postman App
- Iframe source code (iframe.html) - This files contains the JS communicator library code that is used to capture events triggered in the editor. NOTE: Update the function URL and the iframe URL to point to your resources.
- Workflow diagram (loose integration workflow.pdf) - This include requesting the output afterwards in addition but it demonstrates what is included in the Postman collection and how the workflow of the customer journey and API requests required.