Skip to main content

Banners & stores

The content APIs behind the advertisement module. Both are exposed as SDK methods rather than as endpoints you call directly.

Available Android · Available iOS

Access these through the SDK

The banner and store placements are documented as SDK methods, and the SDKs handle the request construction and the parsing of the tagged tracking strings.

TBD A standalone, publisher-facing HTTP API for advertisement placements is not published. If you need placements on a surface with no Cheggout SDK — a headless integration, or a cross-platform app — raise it with Cheggout. It is on Open items.

Shared parameters​

Both calls take the same parameter set.

ParameterTypeRequiredDescription
languageCodestringYesTwo-character ISO language code, for example EN
virtualIdstringYes, except pre-loginThe customer, for personalisation
placementIdstringYesThe slot. 01 for a banner position, 00 for the store row.
securityKeystringOptionalPass an empty string unless Cheggout instructs otherwise
additionalParamsstringOptionalJSON string of location, device and demographic context

virtualId is mandatory except in pre-login, which is the one state where you have a screen but no identified customer. See Placements.

Banners​

CHEGNetworkCallHelper.Companion.getTopBannerDetails(
    virtualId,
    placementId,
    "EN",
    securityKey,
    additionalParams,
    object : CHEGTopBannerCallBack {
        override fun onResponse(responseString: String) { }
    }
)

Response fields​

FieldTypeDescription
bannerLinkstringURL of the creative image to display. Documented with a maximum length of 500 characters.
hrefstringDeep-linking and impression tracking information. Documented with a maximum length of 1000 characters. Pass to the SDK on display and on click.
bankLinkstringDocumented values are 0 and 1. bankLink = 1 means the banner is the Bank's own and the Bank app must not call the SDK. TBD Samples also show an empty string; what an empty value means is not documented.
durationintegerAuto-scroll duration in seconds, for rotating banners
trackLink, trackLinkExtstringTracking information
clickLinkstringClick destination
bankBannerbooleanPresent in the response. TBD No semantics are documented for this field, and its relationship to bankLink is not documented either — do not infer one from the other.
brandDescriptionstringCreative description text

Banners are returned grouped by placement:

Synthetic
{
  "banners": {
    "01": [
      {
        "bannerLink": "https://assets.example.com/banner-1.jpg",
        "href": "REPLACE_TRACKING_STRING",
        "trackLink": "REPLACE_TRACKING_STRING",
        "trackLinkExt": "REPLACE_TRACKING_STRING",
        "bankBanner": false,
        "duration": 10,
        "bankLink": "",
        "clickLink": "https://example.com/destination",
        "brandDescription": "Example promotional description"
      }
    ]
  }
}

Full integration guidance: Banners.

Stores​

CHEGNetworkCallHelper.Companion.getTopStoreDetails(
    virtualId,
    placementId,
    "EN",
    securityToken,
    additionalParams,
    object : CHEGTopOfferCallBack {
        override fun onResponse(responseString: String?) { }
    }
)

Response fields​

FieldTypeDescription
storeIdstringMerchant identifier
titlestringStore name — display it
logostringLogo image URL
discountPercentagestringCurrent discount — display it
categorystringStore category
hrefstringDeep-linking and tracking information
Synthetic
[
  {
    "storeId": "318",
    "title": "Example Retailer",
    "logo": "https://assets.example.com/store-318.png",
    "discountPercentage": "15",
    "category": "Fashion",
    "href": "REPLACE_TRACKING_STRING"
  }
]

Full integration guidance: Stores.

The href tracking string​

Both responses carry href as a pseudo-XML tagged string rather than a plain URL:

<click>https://example.com/destination</click>
<track>https://tracking.cheggout.com/REPLACE</track>
<clicktrack>https://tracking.cheggout.com/REPLACE</clicktrack>
<browser>Native</browser>
<expiryduration>60</expiryduration>
<id>REPLACE_ID</id>
<redirectURL>REPLACE_URL</redirectURL>
TagPurpose
<click>The destination
<track>Impression URLs — fire on visibility
<clicktrack>Click URLs. Pass href to the SDK on launch as documented. TBD Whether the SDK also fires this URL itself is not documented — confirm with Cheggout, and do not assume it is handled for you.
<browser>Rendering hint, Native or Custom
<expiryduration>Present with an observed value of 60. TBD Its meaning is not documented.
<id>Identifier for this tracking record
<redirectURL>Redirect destination

The SDKs parse this for you — pass href to the tracking method and to the launch payload. If you are parsing it yourself, extract the tag you need and fire the URL with a plain GET.

Tracking​

EventMethod
Banner or store becomes visibleAndroid CheggoutUtils.Companion.trackLink(href, virtualId) · iOS CheggoutApp.impression(userID:impressionInfo:)
Customer tapsOpen the SDK with href in the launch payload

See Ad tracking.

Errors​

TBD No error catalogue is published for these calls. Treat an empty or absent response as "no content for this placement" — a normal outcome under frequency caps and targeting — and fail quietly rather than showing an error.

Next​