There are two options to connect your project to your custom UI, using web API keys or using a token server. The easier and more secure option is using the web API keys method.
If you have an orchestration server, you should use the advanced connection configuration on the Project Summary page. For details see Connecting using Token Server.
Connect Using API Keys
On a high level you would need to follow the below steps:
Create and deploy your project from Digital DNA Studio > New Project.
Create an API key and assign it to your project from the settings cog > API Keys > Create API Key.
To connect to your UI, pass in your web API key as an option when constructing your scene.
Creating API Key for Web UI
Create a web API key from the settings cog icon on the top right corner of the screen, select API Keys, and click Create API Key. The new API Key can then be assigned to your project with the specified domains it can be authenticated against.
Field | Description |
|---|---|
Name | Name for the new API key. |
Scope | Choose Web for configuring a Web API Key. |
Assign Project | Start typing the name of the project you wish to generate the API key for. Choose the name of the project from the dropdown list. You can search the project using the project name or project ID. Note: The project must be deployed before you create a Web API Key. |
I'm Developing Locally | If you are developing locally for testing your project, enable this toggle and enter the Public IP Address IPv4 or IP46 with Subnet Mask. |
Enable cross page persistence | This toggle allows the session with Digital Person to continue across multiple pages on a domain or subdomain. See Session Persistence for more details. |
Custom UI Domain | When you are ready for deploying the project, specify one or more web domain(s) in the Custom UI Domains field. |
Expiration | The expiration for web API key is set to never by default. Until its revoked manually. |
On successful creation, the API key is displayed for you to save or copy. Once your API Key is generated, you can view it at any time on the API Keys view screen.
You should revoke the key if it becomes inactive, lost, or compromised. For details see Revoke API Key.
Creating API Key for Mobile UI
Similar to the web API key, you can create API keys to connect to mobile UI (Android and iOS). In this case, select the scope as Mobile.
Field | Description |
|---|---|
Name | Name for the new API key. |
Scope | Choose Mobile for configuring an API Key for Android or iOS UI. |
Assign Project | Start typing the name of the project you wish to generate the API key for. Choose the name of the project from the dropdown list. You can search the project using the project name or project ID. Note: The project must be deployed before you create the API Key. |
Application IDs | A unique name for your mobile app. |
Expiration | The expiration for API key is set to never by default. Until its revoked manually. |
Tips for API key usage
Create one key for local development with IP restrictions and create another key for the public domain without IP restrictions. You should NOT combine them.
If you are developing locally, we recommend you create your own API key. You can use a tool like Show My IP to find your IP address.
Studio is not supporting IP range configuration right now, you would need to add all IP addresses manually.
Troubleshooting
Invalid API key error
Check the browser console logs for any errors. If you see an error message like “Access to fetch at ‘…..’ from origin ‘…..’ has been blocked by CORS policy…”, verify that the 'origin' domain (the exact URL hosting your Digital Person) is correctly specified in the "Custom UI Domains" field of the API key you are using. This includes specifying the correct subdomain - eg, https://www.example.com vs https://example.com
Studio API key configuration is not correct. Double check CUSTOM UI DOMAINS and PUBLIC IP ADDRESSES & SUBNET MASK configuration in Soul Machines Studio, refer to the Tips for API key usage section.
If developing locally with IP address restriction, with VPN your IP could be dynamic, make sure all IP addresses are listed in PUBLIC IP ADDRESSES & SUBNET MASK
When the same API key sometimes works and sometimes doesn't, it could be a server-side error, so please save and hand over the HAR file of the bad request to our customer support.
Confirm you have cleared the “Public IP Addresses & Subnet Mask” field when switching between developing locally and deploying to a remote server. Please note, toggling “I’m developing locally” to false does not clear the field. A previous local address restriction may incorrectly remain in the API Key and cause CORS validation to fail. To mitigate this issue please enter edit mode for the API Key and click "Update Key" a second time.
No API key error but cannot connect, the widget always shows 95% loading progress
Check if your studio project is using HumanOS 2.4+ version, this is required for Session Persistence.
JavaScript console error: blocked by CORS policy
Access to fetch at [SoulMachines] has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
The request header referrer policy does not satisfy CORS policy. CORS policy at site level may be required. Example:
<head><meta name="referrer" content="strict-origin-when-cross-origin"/></head>
Related Topics
Contents