API Responses

Integration Recommendations

When integrating the API on an advertising platform, it must be remembered that a call to an external API can always end unsuccessfully. There are many reasons for this - network infrastructure instability, Roskomnadzor blocks, server-side errors, or simply human factor. Therefore, we recommend considering the possibility of receiving a non-standard response and working this out from the perspective of the website or mobile application's appearance. This is especially important for the home page - if the promo material takes up a large part of the screen, then perhaps filling this space with default content should be provided.

It is mandatory to set some reasonable timeout on all external requests to maintain interface responsiveness.

Also, do not forget that receiving empty promo material (response 204) is a completely standard and frequent situation that occurs if no campaign is launched for the requested user segment.

It is worth providing for the possibility that the request result may have an unexpected format. Campaigns can provide different content variants presented in different forms. These can be banners, product shelves, branded product shelves, etc. Each content variant will have its own logic for rendering and tracking the fact of viewing. Variants of this content are always limited by the acceptContent parameter, which guarantees the predictability of the request result, however, a general practice is to provide for and handle unknown content format.

🚧 ORD (Advertising Data Operator)

If a campaign with content type Banners / SharedBanners is launched in a jurisdiction where the advertising law is in force, then as a result of the ad request, information about the legal entities that are the authors of the creatives (eridToken, advertiserLegalName, advertiserInn, advertiserOgrn) is returned.

Impression

Contains data for displaying sponsored content. Can take different forms depending on the value passed in the acceptContent request.

acceptContent values:

• string
• productIds
• banners
• sharedBanners
• sharedProductIds

StringImpression

Field Name	Required	Type	Description
id	Yes	string	Identifier of the requested impression
contentType	Yes	string	Content type. Always equal to string
content	Yes	StringImpressionContent	Content for display

StringImpressionContent

String content for display

Field Name	Required	Type	Description
id	Yes	string	Content identifier
string	Yes	string	Arbitrary text

Examples

An object of type Impression with a content field of type "string".

{
    "id": "impression identifier",
    "contentType": "string",
    "content": {
        "id": "content identifier",
        "string": "any string"
    }
}

ProductIdsImpression

Field Name	Required	Type	Description
id	Yes	string	Identifier of the requested impression
contentType	Yes	string	Content type. Always equal to productIds
content	Yes	ProductIdsImpressionContent	Content for display

ProductIdsImpressionContent

Content for displaying a product shelf

Field Name	Required	Type	Description
id	Yes	string	Content identifier
productIds	Yes	number array	Array of product identifiers for playback

Examples

An object of type Impression with a content field of type "product shelf".

{
    "id": "impression identifier",
    "contentType": "productIds",
    "content": {
        "id": "content identifier",
        "productIds": [123, 321]
    }
}

BannersImpression

Field Name	Required	Type	Description
id	Yes	string	Identifier of the requested impression
contentType	Yes	string	Content type. Always equal to banners
content	Yes	BannersImpressionContent	Content for display

BannersImpressionContent

Content for banner display

Field Name	Required	Type	Description
id	Yes	string	Content identifier
banners	Yes	Banner array	Array of banners for display
ord	No	object	Object with information for ORD

Ord

Field Name	Required	Type	Description
eridToken	Yes	string	ERID token
advertiserLegalName	Yes	string	Legal entity
advertiserInn	Yes	string	TIN
advertiserOgrn	Yes	string	PSRN

Banner

Banner information

Field Name	Required	Type	Description
targetUrl	No	string	URL to navigate to when clicking the banner
pictureURl	Yes	string	Image URL

Examples

An object of type Impression with a content field of type "banners".

{
    "id": "impression identifier",
    "contentType": "banners",
    "content": {
        "id": "content identifier",
        "banners": [
            {
                "targetUrl" : "http://host/path",
                "pictureUrl": "http://host/path/image.png"
            }
        ],
        "ord": {
            "eridToken": "<erid token>",
            "advertiser": {
                "legalName": "<legal name>",
                "inn": "<inn>",
                "ogrn": "<ogrn>"
            }
        }
}

SharedBannersImpression

Content for displaying shared banners. Differs from BannersImpression in that banners from different advertisers can be present here.

Field Name	Required	Type	Description
id	Yes	string	Identifier of the requested impression
contentType	Yes	string	Content type. Always equal to sharedBanners
content	Yes	BannersImpressionContent array	Content for display

BannerImpressionContent

Content for banner display

Field Name	Required	Type	Description
id	Yes	string	Content identifier
banner	Yes	Banner	Banner for display
ord	No	object	Object with information for ORD

Ord

Field Name	Required	Type	Description
eridToken	Yes	string	ERID token
advertiserLegalName	Yes	string	Legal entity
advertiserInn	Yes	string	TIN
advertiserOgrn	Yes	string	PSRN

Examples

An object of type Impression with a content field of type "shared banners".

{
    "id": "impression identifier",
    "contentType": "sharedBanners",
    "content": [
        {
            "id": "content identifier",
            "banner": {
                "targetUrl" : "http://host/path",
                "pictureUrl": "http://host/path/image.png"
            },
            "ord": {
                "eridToken": "<erid token>",
                "advertiser": {
                    "legalName": "<legal name>",
                    "inn": "<inn>",
                    "ogrn": "<ogrn>"
                }
            }
        },
        {
            "id": "content identifier",
            "banner": {
                "targetUrl" : "http://host/path",
                "pictureUrl": "http://host/path/image.png"
            },
            "ord": {
                "eridToken": "<erid token>",
                "advertiser": {
                    "legalName": "<legal name>",
                    "inn": "<inn>",
                    "ogrn": "<ogrn>"
                }
            }
        }
    ]
}

SharedProductIdsImpression

Content for displaying products from different advertising campaigns. Differs from ProductIdsImpression in that shelves of different advertisers can be present here.

Field Name	Required	Type	Description
id	Yes	string	Identifier of the requested impression
contentType	Yes	string	Content type. Always equal to SharedProductIds
content	Yes	ProductIdsImpressionContent array	Content for display

ProductIdsImpressionContent

Content for displaying a product shelf

Field Name	Required	Type	Description
id	Yes	string	Content identifier
productIds	Yes	number array	Array of product identifiers for playback

Examples

An object of type Impression with a content field of type "shared products".

{
    "id": "impression identifier",
    "contentType": "SharedProductIds",
    "content": [
        {
            "id": "content identifier",
            "productIds": [345]
        },
        {
            "id": "content identifier",
            "productIds": [123]
        }
    ]
}