What is a widget key
A widget key is the value that tells a widget on your site which account and which agent it belongs to. The long string in the installation code is this key.
The widget identifies where it belongs from this single key. Change the key, and the persona and knowledge the widget loads change with it.
It is not a value you use once at installation and forget. You come back to it when you open another site, when the person in charge changes, or when a key is exposed.
How keys are tied to domains
Keys are issued per domain. The widget appears only on the domain the key was issued for, and the same key does not work on any other address.
Here, domain means the address must match exactly. A key issued for example.com cannot be used on shop.example.com, and the reverse is also true. If you run a store and a brand site separately, issue a key for each.
You can also issue keys for the same domain more than once. Each issue adds one new key, and existing keys stay active. This is how you separate test and production keys or give an outside developer their own key.
Who can see keys
Key values are shown only to the account admin. Members who are not admins see only which domains have keys, how many, and whether each is active. In place of the key, they see a notice that the key is visible to admins only.
Issuing keys also requires the Admin role. Even when a developer handles the installation, the key is issued from the admin account and then passed on.
When you reissue a key
If a key has been exposed, reissue it to block it. Reissuing creates a new key and immediately invalidates the previous one.
The new key is shown only once, right after reissue. When you open it again, it appears masked, so copy it on the spot.
The key in the installation code on your site must also be replaced with the new value. Until then, the widget does not appear on that site.
Keys you no longer use can be deleted. Deleting a key makes it inactive, and deleting a key that is already deleted or does not exist does not cause an error.
Where the widget code is loaded from
The first line of the installation code is the address the widget code is downloaded from. You can leave the default as is, but you can set it yourself if the code must be loaded from a different address.
Unlike other values set per key, this address applies to all active keys in the account at once. You cannot have only one site use a different address.
| Setting | Result |
|---|---|
| Left empty | Widget code loads from the default CDN address |
Address starting with https:// | All active keys load the code from that address |
Next steps
- For the screen where you issue and manage keys, see Widget settings.
- For how to add an issued key to your site, see Widget installation.
- If the widget does not appear on your site, see Widget not showing.