Skip to main content

Banner integration

Personalised banner creatives, served into a placement on your screen.

Available Android · Available iOS

The three steps​

The contract is short but each step matters — skipping step 2 breaks attribution, and skipping the href in step 3 breaks the destination.

Step 1 — Fetch​

CHEGNetworkCallHelper.Companion.getTopBannerDetails(
    virtualId,
    placementId,      // e.g. "01"
    "EN",
    securityKey,
    additionalParams,
    object : CHEGTopBannerCallBack {
        override fun onResponse(responseString: String) {
            // Parse and render
        }
    }
)

Parameters are documented on Placements.

Step 2 — Display and track the impression​

Render the creative from bannerLink, then fire the impression when it becomes visible.

CheggoutUtils.Companion.trackLink(href, virtualId)

Pass the banner's href field — the SDK parses the tracking information out of it.

Visible, not loaded

Fire when the banner is actually on screen. Firing at fetch time counts impressions for banners the customer never saw, which inflates your numbers and corrupts reporting. For a carousel, fire per slide as each becomes visible.

Step 3 — Handle the tap​

When the customer taps, open the Cheggout SDK and pass the banner's href in the launch payload. The SDK resolves the destination from it.

TBD Whether the SDK also fires the click URL itself is not documented. Confirm with Cheggout, and do not assume it is handled for you. See Tracking.

See Android launching and iOS launching for the payload field.

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 this to the SDK on display and on click.
bankLinkstringDocumented values 0 and 1 — see below
durationinteger, secondsAuto-scroll duration for rotating banners
trackLink, trackLinkExtstringTracking information
clickLinkstringClick destination
bankBannerbooleanPresent in the response. TBD No semantics are documented for it.
brandDescriptionstringDescription text for the creative

bankLink = 1 means the banner is the Bank's own, and the Bank app must not call the SDK when it is tapped. Handle that banner with your own navigation instead.

This lets your own promotional content share the same carousel as Cheggout's without sending customers into the marketplace when they tap it.

TBD Two things about this field are undocumented. The sample response below carries "bankLink": "" — an empty string, which is neither of the two documented values, and no meaning is given for it. The response also carries a separate bankBanner boolean, and the relationship between the two fields is not stated anywhere. Test only for the documented value 1; do not invent a truthy test across both fields, and confirm the empty case with Cheggout.

Response shape​

Banners are grouped by placement:

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

The href value is a pseudo-XML tagged string carrying several URLs plus display metadata. The SDKs parse it for you. If you are integrating headlessly, extract the tag you need and fire the URL with a plain GET. See Tracking.

Rendering guidance​

Honour duration for rotating carousels rather than hardcoding a rotation interval — it is set per creative.

Handle an empty response as normal. Targeting and frequency caps mean a placement will legitimately return nothing. Collapse the slot or show your own fallback; do not log an error.

Fail quietly. If the fetch fails, show nothing. A banner is not worth an error state on your home screen.

Cache carefully. Creatives are personalised and subject to frequency caps, so caching a response across sessions will show stale content and misreport impressions. Fetch per screen visit.

Reserve layout space consistently so a late-arriving banner does not shift content under the customer's finger.

Next​