> For the complete documentation index, see [llms.txt](https://help.smartico.ai/welcome/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.smartico.ai/welcome/technical-guides/front-end-integration/extended-integration/secure-identification-and-special-setups.md).

# Secure identification and special setups

This page explains how to protect player identification with a hash, how to open the Gamification widget from your own back office, how to integrate when your site runs inside an iframe, and how to test on localhost.

## Protecting user identification on the public front-end

The simple user identification is based on the unique ID of the user set in the \_smartico\_user\_id

```javascript
<script>
    window._smartico_user_id = 'some_id';
    window._smartico_language = 'fr';
</script>
```

In case the user ID can easily be guessed (e.g. it's a sequential number or just a string that corresponds to the username), there are additional mechanics to protect identification.

You will need to calculate a hash string from the user ID, secret salt key, and validity timestamp. The calculation formula is the same as described [here](#opening-gamification-widget-from-operators-backoffice). The hash should be calculated on the server(!) and passed in the front end in the following way. For the Smartico script, Smartico checks the hash against the user ID in lower case, without spaces at the start and end, so build the hash from the user ID in the same form (for example `ABC123` → `abc123`). The public HTTP API checks the hash against the user ID exactly as you send it.

```
<script>
    window._smartico_user_id = 'some_id';
    window._smartico_language = 'fr';
    window._smartico_user_hash = '019b370929095f0cfe6c9b02ea7524a2:1638050700000';
</script>
```

The salt key should be requested from Smartico Customer Success Manager and should be kept in secret. The check is enforced when the **Require a signed hash to identify players** setting in **Label settings** is on. Turn it on only after your site sends the hash: without a valid hash the user is not identified.

## **Opening gamification widget from operator's backoffice**

The gamification widget can be opened in read-only mode from 3rd party sites.

The most common reason for this is to provide the Support team the possibility to see the current status of the gamification setup as the end-user sees it.

The widget can be opened using the URL:

```url
https://libs.smartico.ai/wrapper-bo.html?label_key=${label_key}&brand_key=${brand_key}&user_ext_id=${user_ext_id}&user_hash=${user_hash}
```

Parameters to be passed:

* label\_key & brand\_key - the same set of public keys for the label & brand as used in the front-end integration for the end user
* user\_ext\_id - identification of the user in the integrated product
* user\_hash - md5 hash and the validity timestamp separated with the ":" symbol

**The user\_hash should be calculated in the following way**

```javascript
const hashValidityTimestampMs = ~~(+new Date() / 1000) * 1000 + 24 * 3600 * 1000;
user_hash = Md5.init(user_ext_id + ":" + "label_salt_key" + ":" + hashValidityTimestampMs) + ":" + hashValidityTimestampMs;
```

Label salt key can be retrieved from label configuration in Smartico BackOffice (the **Secret 'salt' key** setting in **Label settings**). Hash validity timestamp is defining the time in epoch with milliseconds till which the hash will be valid. A hash whose timestamp has passed is rejected. Write the MD5 value in lower-case hex, as in the example below.

Example of calculation:

```
label_key = 3ff6261b-00a7-4137-9906-de7450fd61c9
brand_key = 13d7ff00
user_ext_id = 879978
label_salt_key = demo-salt
timestamp = 1638050700000 // Sat Nov 27 2021 22:05:00 GMT+0000
user_hash = 019b370929095f0cfe6c9b02ea7524a2:1638050700000
```

Example of JavaScript code opening a widget in the iframe and closing it when the widget is closed from inside:

```javascript
const ifr = document.createElement('iframe');
document.body.appendChild(ifr);
ifr.style.cssText = 'position:absolute;width:90vw;height:90vh;top:5vh;left:5vw;border: 3px dotted black;z-index:99999';
ifr.src = `https://libs.smartico.ai/wrapper-bo.html?label_key=${label_key}&brand_key=${brand_key}&user_ext_id=${user_ext_id}&user_hash=${user_hash}`;
window.addEventListener("message", function (event) {
   if (event.data === 'close-gamification-frame' && ifr) {
       ifr.remove();
   }
});

```

Smartico BackOffice is using the same approach to show the gamification widget of any user in the CRM section

<div data-with-frame="true"><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-fc39a5726f9d66fd3c06f594a98a129ddccff1e3%2Ff52b7f7220-crop-7-3761ef67-9195f6.png?alt=media" alt=""><figcaption><p>View on gamification state of specific user from the Smartico BackOffice</p></figcaption></figure></div>

## **IFrame bridge (B2B)**

If the integrated platform is loaded in the iframe and not the owner of the main window, the setup should be done in a different way.

The site that owns the main window should load only the Smartico script without doing initialization of the label/brand and identifying the user. HTML code to paste as is:

```html
<script>
(function(d, r, b, h, s){h=d.getElementsByTagName('head')[0];s = d.createElement('script');s.onload=b;s.src=r;h.appendChild(s);})
(document, 'https://libs.smartico.ai/smartico.js');
</script>
```

The iframe should load **smartico\_inframe.js** script and makes the same calls as described in [Front-end integration](https://help.smartico.ai/welcome/technical-guides/front-end-integration.md) and the other [Extended integration](https://help.smartico.ai/welcome/technical-guides/front-end-integration/extended-integration.md) pages, but using ***\_smartico\_inframe*** object instead of **\_smartico**.

Only these methods are available on **\_smartico\_inframe**: `dp`, `init`, `identify`, `online`, `login`, `logout`, `changeLanguage`, `event`, `action`, `setAvatar`, `miniGame` and `suspendPopups`. The main window ignores other calls. It also accepts calls only from an iframe placed directly on its page, not from a nested iframe or a separate window.

Example of the script

```html
<script>
   (function(d, r, b, h, s){h=d.getElementsByTagName('head')[0];s = d.createElement('script');s.onload=b;s.src=r;h.appendChild(s);})
   (document, 'https://libs.smartico.ai/smartico_inframe.js', function() {
       _smartico_inframe.init('__your_label_key', { brand_key: '__your_brand_key__' });
       _smartico_inframe.online('some_user_id', 'fr');
       // open gamification widget
       _smartico_inframe.dp('dp:gf');
   });
</script>  
```

{% hint style="info" %}
Please contact your Customer Success Manager to evaluate if your setup needs this type of integration.
{% endhint %}

## Debug/develop on the localhost

By default, the Smartico script is not allowed to be used on the localhost.

This is done to prevent the creation of "phantom" users when the script running on localhost is usually connected to the DEV/QA environment, and the user that reported from this environment will be sent to Smartico, which will lead to the creation of the users that shouldn't be on production.

If you want to run on localhost and you are going to use a real/production user, you can enable debugging on the localhost

```javascript
window._smartico_allow_localhost = true;
```

The **Domains where the Smartico script may run** setting in **Label settings** limits the domains where the script identifies the user. Enter a comma-separated list of domains, for example `mobile.mysite.com,mysite.com`. A domain matches when the site address ends with it, so `mysite.com` also matches `another-mysite.com`. On other domains the script does not identify the user. When the setting is empty, the script works on any domain except localhost. You can also set it for one brand, on the **Brand settings** tab of that brand.

To allow localhost without the flag above, add `localhost` to this list, together with your real domains.

## Frequently Asked Questions (FAQ)

### How do I configure user identification protection with a Salt Key?

To protect against user identification tampering on the front end, request a secret salt key from your Customer Success Manager or obtain it from Label Settings in the Back-Office (the **Secret 'salt' key** setting). Enable the setting **Require a signed hash to identify players** in Label Settings.

On your backend server, generate an MD5 hash using the external user ID, the secret salt key, and an expiration timestamp (milliseconds since epoch, e.g. valid for 24 hours):

`MD5(user_id + ":" + salt + ":" + timestamp) + ":" + timestamp`

Pass this value on the front end as `window._smartico_user_hash` or via the identification method. Keep the salt key exactly as it is. For the Smartico script, use the user ID in lower case, without spaces at the start and end, because Smartico checks the hash against the user ID in this form. Write the MD5 value in lower-case hex.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.smartico.ai/welcome/technical-guides/front-end-integration/extended-integration/secure-identification-and-special-setups.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
