These instructions are for new implementations of Luxiflux Zonal.
If you are migrating from our previous product, follow the instructions for migrating from Flash Indoor instead.
In this step you will:
- Create a URL to launch Luxiflux Zonal.
- Create a web API.
- On your website
- Which can be called by the Luxiflux Zonal tool
- Which returns input to initialize the tool
- Test it.
Step 2.1 Create an Input Web API URL
You need to create a web API on your website.
Decide what the URL for the API will be.
Example:
https://www.example.com/Luxiflux/Zonal/Input
Step 2.2 Build a URL to launch Luxiflux Zonal
Build a URL that launches Luxiflux Zonal.
The URL consists of the following parts (they are case sensitive):
https://v1-zonal-tools.luxiflux.com | Required | The URL for the Luxiflux Zonal website. |
AuthenticationUrl | Required | You should have an authentication web API and its associated URL after completing the authentication step of these instructions. |
InputMode | Required | The input mode (format) returned by the InputURL. The value should be set to: JSON |
InputUrl | Required | The absolute URL that returns the input JSON data. This should be a URL to a web API that generates and returns JSON as an HTTPS response. In rare cases this might be a URL to an JSON file on a server (i.e. for testing). |
InstanceKey | Optional | You can specify a custom InstanceKey which is passed (in an HTTPS POST request) to the InputURL. You can then use this Instance Key to modify the response of your Input Web API. If the Instance Key is generic (always the same) each time the tool is launched, it can be omitted. |
Example (broken into multiple lines for clarity):
http://v1-zonal-tools.luxiflux.com ?AuthenticationUrl=https://www.example.com/Luxiflux/Authentication &InputMode=JSON &InputUrl=https://www.example.com/Luxiflux/Zonal/Input &InstanceKey=AnyInstanceKey
Example (no line breaks):
http://v1-zonal-tools.luxiflux.com?AuthenticationUrl=https://www.example.com/Luxiflux/Authentication&InputMode=JSON&InputUrl=https://www.example.com/Luxiflux/Zonal/Input&InstanceKey=AnyInstanceKey
Step 2.3 Strategy
Chances are that you want to launch the Luxiflux Zonal tool:
- From different places on your website.
- With different inputs depending on the context.
There are two ways to do this.
Strategy A Multiple Input URLs
When you want to launch Luxiflux Zonal with different inputs you can create multiple Input Web APIs.
Examples:
InputUrl=https://www.example.com/Luxiflux/Zonal/Input/ProductFamily1 InputUrl=https://www.example.com/Luxiflux/Zonal/Input/ProductFamily2 InputUrl=https://www.example.com/Luxiflux/Zonal/Input/ProductFamily3
Strategy B Multiple Instance Keys
If you include the InstanceKey parameter in the launch URL, it is passed through to your web API. You can then use it to determine how to dynamically change the output of you API.
Examples:
InstanceKey=ProductFamily1 InstanceKey=ProductFamily2 InstanceKey=ProductFamily3
Strategy C Combined
You can also combine both strategies.
You can create multiple APIs for the InputUrl parameter while also providing different values for the InstanceKey parameter.
Other Considerations
You should consider how website (and your website data/content) is organized, how often you intend to update your website, who needs to perform the updates, and the protocols and workflows required.
Step 2.4 Examine the Luxiflux Zonal Input Data
Please reference the following links:
- LuxifluxZonal_InputExample
- An example of the JSON response that must be returned by your Input Web API.
- The JSON data returned by your Input Web API is used as input to initialize the Luxiflux Zonal tool.
- LuxifluxZonal_InputComments
- Contains comments and documentation for each item in the JSON data.
When the Luxiflux Zonal tool is launched it will send an HTTPS web request to the web API specified in the InputUrl.
If you include the InstanceKey parameter:
The tool will make a POST request to your web API with the following JSON data.
{ "InstanceKey": "AnyInstanceKey" }
Otherwise:
The tool will make a GET request to your web API.
The web API should return valid JSON with the specified data (see the example JSON file attatched to this article).
Step 2.5 Decide on Static and Dynamic Input Data
The JSON data your web API provides can be divided into two categories.
- Static -- Data that is the same every time the tool is launched.
- Typically includes logos, colors, units, etc.
- Dynamic -- Data that changes every time the tool is launched.
- Typically includes photometry, etc.
You need to decide which portions of the JSON data will be static and dynamic in your case.
This can help you determine which strategy you employ when integrating the tool into your website.
Your web API needs to combine the static and dynamic portions of the data and provide the result as input to the tool.