Skip to main content

Getting Started

This guide walks you through:

  1. Authentication
  2. Fetching a personalized offer
  3. Opening the offer page
  4. Handling user engagement
  5. Tracking offer completion

For a visual overview of the complete offer flow, see the Offers page.

Authentication​

All requests to the Toffee gCOM API must include your publishable or secret key. See the Authentication page for details.

Fetch a Personalized Offer​

Send a server-side or client-side request to fetch a personalized offer for your user. See the Offers page for detailed API documentation.

Quick Example:

POST /toffee.v1.OfferService/FetchOffer
Authorization: Bearer <your_publishable_key>
{
  "user_id": "player_42",
  "user_metadata": {
    "level": "15",
    "achievements": "speedster,collector"
  },
  "used_devicedata": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Open the Offer Page​

Open the returned offer url in a webview within your game.

The user will:

  • View personalized promotional content
  • Engage with videos, images, or interactive offers
  • Complete actions like watching ads or making purchases

Example:

{
  "id": "offer_abc123",
  "url": "https://show.toffee.com/offer_abc123",
  "status": "available"
}

Handle User Engagement​

As users interact with the offer content, Toffee automatically tracks engagement:

  • Video/Image Promos: Heartbeat calls track viewing progress
  • Interactive Offers: User actions like clicks and form submissions are recorded

The offer status automatically updates from available → shown → engaged → redeemed

See the Offers page for complete engagement tracking details.

Tracking Offer Completion​

Monitor offer status and handle completion in your game using webhooks for real-time updates. See the Webhooks page for implementation details.

Alternative - Check Offer Status:

POST /toffee.v1.OfferService/GetOffer
Authorization: Bearer <your_secret_key>
{
  "id": "offer_abc123"
}