Placements
A placement is a slot in your UI that Cheggout can fill. You integrate the slot once; Cheggout decides what goes in it, and can change that at any time without you shipping an app update.
Why placements rather than campaigns
If your app requested "the summer offer campaign", every campaign change would need a release. By integrating a position instead, the decision of what to show moves server-side — which is where targeting, eligibility, frequency capping and inventory already live.
Parameters
Every placement request takes the same shape.
| Parameter | Type | Required | Description |
|---|---|---|---|
languageCode | string | Yes | Two-character ISO language code, for example EN |
virtualId | string | Yes, except pre-login | The user, for personalisation |
placementId | string | Yes | Which slot this is, for example 01 for a banner or 00 for the store row |
securityKey | string | Optional | Pass as an empty string unless Cheggout tells you otherwise |
additionalParams | string | Optional | A JSON string of extra context |
The pre-login case
virtualId is mandatory except in pre-login, which is the one state where you have a screen but
no identified user.
| State | virtualId | What you get |
|---|---|---|
| Logged in | Sent | Personalised content |
| Pre-login | Omitted | Non-personalised content |
Handle both. A publisher's splash or login screen is often its highest-traffic surface, and a placement that only works after authentication misses it entirely.
additionalParams
Extra context that improves targeting — location, device and demographic signals you already hold. Send it as a JSON string, not a nested object.
Fields observed across integrations include country, state, district, city, pincode, store identifier, IP address, latitude and longitude, gender, age, and a new-user flag.
{ "city": "Bengaluru", "state": "Karnataka", "pincode": "560001" }
Send only what you legitimately hold and are permitted to share. Location and demographic data carry privacy obligations that are yours, not Cheggout's.
TBD The authoritative list of accepted additionalParams fields for placements
is not published, and it differs between banner, store and reward calls. Confirm the set that
applies to your placements during onboarding.
Placement IDs
placementId identifies the slot. Documented examples are "01" for a banner position and "00"
for the store row.
TBD No placement registry is published. There is no self-service list of valid IDs, no way to see what each maps to, and no way to create a placement yourself. Your channel's placement map is configured by Cheggout during onboarding — ask for it explicitly, including which IDs are valid in UAT versus production.
This is a P0 item on Open items.
Designing your placements
Declare more slots than you fill. A placement that returns nothing costs a request; a screen without a placement cannot be monetised until your next release. Add slots to screens you might want to use later.
Reserve layout space thoughtfully. A banner slot that collapses to zero height when empty avoids a visible gap; one that reserves height avoids layout shift when content arrives. Pick per screen and be consistent.
Handle the empty response as normal. Frequency caps and targeting mean a placement will legitimately return nothing. That is not an error and should not be logged as one.
Request when the screen is built, fire the impression when it is visible. These are different moments, and conflating them inflates your impression counts and corrupts reporting. See Tracking.