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.
Overview
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.
We then use a JavaScript communicator library that you will need to include on your page that is hosting the iframe to capture events like 'Add to basket' or 'Save as project'. When these events are triggered, you can then react to this information and act accordingly.
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. As an iFrame requires a binding and SSL (it cannot be setup without it) we will implement these free of charge.
1. Get the Customer GUID (Optional)
GET services/api/Customer/Get/{id}
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.
GET services/api/Customer/Get/{id}
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
GET services/api/Editor/LinkFor/{id}?productId={productId}&errorUrl={errorUrl}&embeddedOperationMode=true
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.
In order to capture certain events that the user carries out in the editor we also require you to include our JavaScript library on your iframe parent page (see resources). This allows you to capture, for example, the 'Add to basket' click event. When this happens you must capture the Job Id that is included in the event data. This Job Id is required later in the process for placing the order to ensure the correct output is generated.
You can also extend this section of the integration to allow for editing existing jobs (either from basket or from saved projects) and to do this you need to pass in with it the Id as the orderlineItemId parameter. If supporting Saved Projects is also required then you can also then capture and handle the 'Save project' event in the editor through the JavaScript communicator library and store the Id and direct the customer to their account.
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:
POST services/api/Order/RecordOrder
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.
POST services/api/OrderlineItem/CreateOutputFor/{id}
Attached Resources
- 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.
0 Comments