Usersplit API

Tip

Developer skills are required to use the Usersplit API. If you don't have experience with coding, consult your site's developer or webmaster.

The Usersplit API connects Varioqub to your site.

Request format

GET https://uaas.yandex.ru/v1/exps
  ? [client_id=<String>]
  & [url=<String>]
  & [i=<String>]
  & [client_features=<String>]
  & [cuid=<String>]

client_id

Yandex Metrica user ID. Format: metrika.{counter_id}. Where {counter_id} is the Yandex Metrica tag ID. How to find your tag ID

url

The page URL with GET parameters that the user is currently browsing.

If you don't pass a URL, Varioqub uses the header referrer, though the referrer might not be passed or might be passed only partially. Because of this, we recommend passing the URL.

i

Site user's ID stored in first-party cookies. Make sure to set it in the _ymab_param cookie upon receiving the response. This value can be empty during a user's first session on your site.

We recommend passing this parameter in every API request. For the first request, this field may be empty.

client_features

Serialized JSON object containing user parameters*. Example: {"param2": "value2", "param1": "value1"}.

cuid

A custom ID that allows you to use your own user IDs in experiments.

To enable this functionality, implement the passing of the GET parameter cuid on the site. The value of the parameter needs to correspond to the user ID. The custom ID must not be longer than 30 characters.

Note

The Usersplit API also uses Referer, User-Agent, and X-Forwarded-For to group users by samples. Make sure they're passed correctly.

HEADERS:
Referer: {url}
User-Agent: {user-agent}
X-Forwarded-For: {user_ip}

where:

  • url: the full URL, including GET parameters, of the page browsed by the user.

  • user-agent: User-Agent of the site user.

  • user_ip: IP address of the site user.

Response format

JSON

{
    "i":"{i}",
    "experiments":"{experiments}",
    "testids": [
        {testid.1},
        ...
        {testid.n}
    ],
    "flags":
    [
        {
            "n":"{flag.1}",
            "v":"{value.1}",
            "t":"{type.1}"
        },
        ...
        {
            "n":"{flag.n}",
            "v":"{value.n}",
            "t":"{type.n}"
        }
    ]
}

Field name

Description

i

Site user's ID stored in first-party cookies. Make sure to set it in the _ymab_param cookie upon receiving the response. It may be empty during the user's first visit to the site.

experiments

Technical data for the Yandex Metrica tag is returned in encrypted form. Once received, pass the data to Yandex Metrica when initializing the tag or by a separate call.

testids

Array of IDs of variants successfully targeted by the user.

The value is displayed in the extended version of Varioqub. In the basic version, the array is empty.

flags

Array of flags that define experimental changes. The array consists of {flag.N}:{value.N} pairs. Unique flags aren't guaranteed in the array, as this depends on experiment settings.

t

Flag type (type). It can have the flag data type.

n

Flag name (name).

v

Flag value (value).

Note

The response format may contain additional fields. When handling the response, process only the parameters necessary for working with the API.

Response example:

{
    "i":"7ASX7O3PO+SD4f30Y1GqkUEVIgyJ+lqpl9teI7DtiRQTGlsMT8VszxKsrU/2D5+mTTJviiKIv2/2
obmd4t7fGkefkfY=",
    "experiments":"JjfiHndoV8s",
    "flags":
    [
        {
            "n":"flag_name",
            "v":"value",
            "t":"flag"
        }
    ],
     "testids": [
        1234,
        4567
    ],
}

Sending technical data to Yandex Metrica

To transmit technical data, use the experiments method. You can call this method either when initializing a tag or separately.

ym(XXXXXX, 'experiments', experiments);
Parameter Type Description
experiments String Technical data for Yandex Metrica, such as information about the variants used in the experiment. This data is returned in encrypted form after a Usersplit API method is called.
Contact support

Yandex Metrica user ID. Format: metrika.{counter_id}. Where {counter_id} is the Yandex Metrica tag ID. How to find your tag ID

Full URL, including GET parameters, of the page browsed by the user.

If no URL is passed, Varioqub uses the referer from the headers. However, in some cases it may not be possible to send the referer in full or at all. For this reason, we recommend always passing the URL.

Site user's ID stored in first-party cookies. Make sure to set it in the _ymab_param cookie upon receiving the response. It may be empty during the user's first visit to the site.

We recommend passing it in each API request. The field may be empty in the first request.

To use it in the experiment, activate the extended version.

Serialized JSON object containing user parameters. Example: {"param2": "value2", "param1": "value1"}.

A custom ID that allows you to use your own user IDs in experiments.

To enable this functionality, implement the passing of the GET parameter cuid on the site. The value of the parameter needs to correspond to the user ID.

Previous
Connecting
Next
Hiding a page until the experiment starts