> 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/serving-smartico-through-your-own-domains.md).

# Serving Smartico through your own domains

The Smartico script, the gamification widget, images and the live connection normally load from Smartico domains: `smartico.ai`, `smr.vc` and Amazon CloudFront. This page explains how to serve all of them from your own domains instead.

## The problem it solves

* **Regional traffic rules.** In some countries, regulations or local Internet providers allow player traffic only to regional or locally approved domains. Requests to global hosting such as Amazon Web Services (AWS) can then be slow or not reach their target, and players see a missing widget, empty images, or no live updates such as points, missions and pop-ups.
* **Compliance.** Some operators must keep all traffic from the player's browser on their own domain.

## The solution

You run a reverse proxy on your own subdomains, and you pass one extra setting, `domains_remap`, to `_smartico.init`. The setting lists which Smartico host is replaced by which of your hosts, and why (its *purpose*).

The Smartico script does the replacement in the player's browser: for the script itself, the gamification widget, pop-ups, images, avatars, inbox messages and the live connection.

* **Nothing changes in the back office.** Your team uploads content and builds campaigns as before.
* **No special build.** You load the standard Smartico script through your proxy, so you get every Smartico release as usual.
* **Easy rollback.** Remove the setting and load the script from its original address, and everything loads from Smartico again.
* **Without the setting, nothing changes.** Current integrations keep working as they are.

{% hint style="info" %}
This option is for operators who run their own proxy. If you prefer that Smartico runs the setup on a subdomain you delegate to us, see "Serving smartico scripts & connectivity from a custom domain" on the [Front-end integration](https://help.smartico.ai/welcome/technical-guides/front-end-integration) page.
{% endhint %}

## Pass the player's real IP to Smartico

{% hint style="danger" %}
**Required.** On every proxy, and above all on the live connection (WebSocket) proxy, the **first** value of the `X-Forwarded-For` header must be the player's real IP address. If your proxy sits behind another CDN (for example Cloudflare), use the player IP that CDN gives you, not the CDN's own address.
{% endhint %}

If the proxy does not pass the player's real IP, all your players reach Smartico from the same IP address: the address of your proxy. Smartico's protection then treats them as one client. **Your players can be limited or blocked all at once**, because one misbehaving client is enough to block that shared address. Player data that depends on location can also be wrong.

During the test on your QA label, Smartico checks that real player IPs arrive, not your proxy's.

## What you need to do

1. **Get your host list.** Ask your Success Manager for the exact Smartico hosts of your label. They depend on the Smartico environment of your label and on the features you use.
2. **Create one proxy subdomain for each host,** following the rules and the table below.
3. **Send Smartico the outgoing IP addresses of your proxy,** so that we can allow them where needed.
4. **Add `domains_remap` to `_smartico.init`** and load the Smartico script from your proxy.
5. **Test on your QA label first,** then move to production in an agreed time window.

### Name your subdomains after ours

We strongly recommend keeping the Smartico subdomain name and the environment number: `static7.smr.vc` becomes `static7.your-domain.com`, `img7.smr.vc` becomes `img7.your-domain.com`. When a player reports a broken image, both teams can see at once which Smartico host and environment it belongs to. Short or generic names such as `img.` or `cdn.` make every support case slower.

### Rules for every proxy

* Serve HTTPS with your own certificate.
* Send the Smartico host name as the `Host` header and in TLS SNI. CloudFront refuses other names.
* Keep request and response headers as they are (CORS, content type, compression).
* Never change the response body.
* Pass the player's real IP as the first `X-Forwarded-For` value (see above).

### Purposes

| Purpose     | What goes through it                                                                                    | Proxy type and methods                                                             | Caching                                                                         | How to check it                                                                                                            |
| ----------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `sdk`       | The Smartico script, its modules, the gamification widget pages and files, pop-up scripts, mini-games   | Static HTTPS: GET, HEAD                                                            | The script and `.html` files: 5 minutes at most. Other files: as Smartico sends | The script loads from your host. Open the gamification widget: the frame and all its files come from your host.            |
| `websocket` | The live connection: player data, missions, store, points, pop-ups                                      | WebSocket (HTTP/1.1 Upgrade). Keep the query string. Idle timeout above 60 seconds | None                                                                            | DevTools, Network, WS: one open connection to your host, with messages. It stays open when the tab is idle for 10 minutes. |
| `avatar`    | Avatars, plus the visitor (not logged in) data, form submits and avatar changes                         | HTTPS API and files: GET, POST, OPTIONS. Request body up to 10 MB                  | As Smartico sends. Never cache POST                                             | A player sees their avatar from your host. A logged-out visitor sees gamification content. Changing the avatar works.      |
| `static`    | Images and media uploaded in the back office, and a few built-in default images                         | Static HTTPS: GET, HEAD                                                            | Long (1 day or more). File names are unique                                     | Missions, store and pop-up images all come from your host.                                                                 |
| `inbox`     | The body of each inbox message                                                                          | Static HTTPS: GET, OPTIONS                                                         | Long. A message never changes after it is sent                                  | Open an inbox message with an image: the body and the image load from your hosts.                                          |
| `games_api` | Prediction games data (only if you use them)                                                            | HTTPS API: GET, POST, OPTIONS                                                      | None                                                                            | Open a prediction game: rounds load and a pick can be saved.                                                               |
| `push_api`  | Delivery and click reports of web push notifications (only if you use them)                             | HTTPS API: GET, POST                                                               | None                                                                            | Click a test push; Smartico confirms the click is reported.                                                                |
| `ide`       | Widgets built in the Smartico IDE (only if you use them). Ask your Success Manager before you set it up | Static HTTPS with a wildcard host: GET, HEAD                                       | `widget.js` and `.html`: 5 minutes at most                                      | The embedded widget renders from your wildcard host.                                                                       |
| `brick`     | Bricks embedded on your page (only if you use them)                                                     | Static HTTPS: GET, HEAD                                                            | Script and `.html`: 5 minutes at most                                           | The brick renders from your host.                                                                                          |

## The init setting

Each entry of `domains_remap` has three fields: `purpose` (from the table above), `from` (the Smartico host) and `to` (your host). The example below is for a label on Smartico environment 7. Use the host list from your Success Manager.

```html
<script src="https://libs.your-domain.com/s.js"></script>
<script>
_smartico.init('_label_key_', {
  brand_key: '_brand_key_',
  domains_remap: [
    { purpose: 'sdk',       from: 'd312ucx3huj7iy.cloudfront.net', to: 'libs.your-domain.com' },
    { purpose: 'sdk',       from: 'libs.smartico.ai',              to: 'libs.your-domain.com' },
    { purpose: 'websocket', from: 'api7.abrws.club',               to: 'api7.your-domain.com' },
    { purpose: 'avatar',    from: 'img7.smr.vc',                   to: 'img7.your-domain.com' },
    { purpose: 'static',    from: 'static7.smr.vc',                to: 'static7.your-domain.com' },
    { purpose: 'static',    from: 'static.smr.vc',                 to: 'static.your-domain.com' },
    { purpose: 'static',    from: 'static5.smr.vc',                to: 'static5.your-domain.com' },
    { purpose: 'inbox',     from: 'd8i6ukeptclx4.cloudfront.net',  to: 'inbox7.your-domain.com' },
  ],
});
</script>
```

The setting is checked when `_smartico.init` runs. When something is wrong, the script stops with a clear error in the browser console that names the entry. It stops when:

* a host has a scheme or a path (use `static7.your-domain.com`, not `https://static7.your-domain.com/`);
* a purpose is not in the table above;
* the same `from` host points to two different `to` hosts;
* a `*.` wildcard is used outside `ide` and `brick`, or only on one side;
* the `sdk` or `websocket` entries do not include the host that your copy of the script really uses;
* the `ws_url` parameter is passed together with a `websocket` entry (use one or the other);
* `_smartico.init` is called again with a different map on the same page.

When the setting is accepted, the console shows `Smartico: domains_remap active` with the list of entries.

## Final check

With the setting on, open your site as a test player and use the gamification features. In the browser's Network panel, filter by `smartico`, `smr.vc`, `cloudfront` and `ld-int.dev`. Only a few third-party services (fonts, animations, error monitoring) should remain. Then tell your Success Manager, and Smartico checks on our side that real player IPs arrive and that avatars are saved correctly.


---

# 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/serving-smartico-through-your-own-domains.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.
