Interactive Ads Quickstart

⏱️ 15-minute integration Bolt Gaming has partnered with ToffeePay to deliver the future of Ads for Gaming. You will likely see some co-branding throughout the integration.

This Quickstart helps you set up Bolt Interactive Ads in a flash ⚡

By the end of this guide you will be able to fetch and display personalized offers to users in your app.

Sections should take no more than a few minutes:

• Create a Bolt Sandbox Account
• Install an SDK
• Get Your API Keys
• Create Personalized Ad Offer
• Enable Webhooks

Create a Bolt Sandbox Account

If you don't have one, create a Bolt Merchant Sandbox account by completing the following steps:

• Enter your company website URL – Use the public website for your game studio or company.
• Provide company details – Add your legal business name, address, and contact information.
• Add sandbox user information – Create a user profile for yourself (and optionally register additional team member).
• Review and confirm – Check that all details are correct, confirm the pricing information, and select Submit.
• Activate your account – Open the activation email from Bolt and follow the link to complete setup.

After activation, you can access your sandbox account here: Bolt Merchant Sandbox.

Install an SDK

We provide lightweight SDKs to help you get started:

• JavaScript SDK · GitHub

Usage

Use the SDK to display interactive ads with BoltSDK.gaming.openAd(). Here's a sample implementation:

// Initialize the Bolt SDK
BoltSDK.initialize({
  gameId: 'your-game-id',
  publishableKey: 'YOUR_PUBLISHABLE_KEY'
});

// Open an interactive ad. openAd takes options only; the ad link comes back in the result.
const adOfferResult = await BoltSDK.gaming.openAd({
  onClaim: () => {
    // fires when the player claims the reward
  }
});

// Handle the result
if (adOfferResult.status === 'success') {
  // TODO – validate the ad offer in the backend for a secure confirmation

  // now you can display a success modal
  console.log('Ad displayed successfully:', adOfferResult.data.adLink);
} else {
  // user exited early – display a failure modal
  console.error('Failed to display ad:', adOfferResult.error);
}

Sample Link for Testing: Use this sample link to test the integration: https://show.sandbox.toffee.com/offer_01k5y8wdbk5b390mmwdz5ja7cd

Get Your API Keys

Once you create a Bolt Merchant account, sign in and navigate to:

• In the left-side menu, Administration → API.

Copy the following into your request headers:

• API Key - for authentication
• Publishable Key - for identifying your public-facing integration

--header 'X-API-KEY: YOUR_API_KEY' \
--header 'X-PUBLISHABLE-KEY: YOUR_PUBLISHABLE_KEY' \

Create Personalized Ad Offer

To get personalized ads for your users you will need to hit the Bolt API.

Note: these apis are still in beta. For now the api will always return a static result but by mid October it will generate unique ad offers per request. Thanks for your patience while we production-ize our new ad tech technology.

curl --location 'https://api-sandbox.boltapp.com/v1/gaming/beta/ad_offer' \
--header 'X-API-KEY: YOUR_API_KEY' \
--header 'X-PUBLISHABLE-KEY: YOUR_PUBLISHABLE_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "user_id": "user-123"
}'

{
  "id": "offer_01k6gs6gxv08j8zm9zmwcq9spm",
  "url": "https://show.sandbox.toffee.com/offer_01k6gs6gxv08j8zm9zmwcq9spm",
  "status": "available",
  "image": "https://cdn.toffee.com/offers/example.png",
  "expires": 3600
}

Metadata

Optionally you can include a user_metadata field to be permanently associated with this ad offer.

Bolt does not rely on this field but it can be useful if you have external IDs you use for analytics. It will be returned on all future requests for this ad offer.

curl --location 'https://api-sandbox.boltapp.com/v1/gaming/beta/ad_offer' \
--header 'X-API-KEY: YOUR_API_KEY' \
--header 'X-PUBLISHABLE-KEY: YOUR_PUBLISHABLE_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "user_id": "user-123",
    "user_metadata": {
        "google-analytic-id": "your-example-id",
        "offer-placement": "game-over-screen",
        "user-tier": "free-user",
        "reward_type": "bolt-buckaroos",
        "reward_amount": "500"
    }
}'

{
  "id": "offer_01k6gs6gxv08j8zm9zmwcq9spm",
  "url": "https://show.sandbox.toffee.com/offer_01k6gs6gxv08j8zm9zmwcq9spm",
  "status": "available",
  "image": "https://cdn.toffee.com/offers/example.png",
  "expires": 3600
}

Verify an Ad Offer

Once an ad is completed by the user, you will need to do a server verification before issuing a reward. You can do this by checking the status of the ad offer.

curl --location GET 'https://api-sandbox.boltapp.com/v1/gaming/beta/ad_offer/YOUR_AD_OFFER_ID' \
--header 'X-API-KEY: YOUR_API_KEY' \
--header 'X-PUBLISHABLE-KEY: YOUR_PUBLISHABLE_KEY'

You will get a response with status marked redeemed if the ad was completed by the user. This means the reward is ready to be issued to the user:

{
  "ad_offer_properties": {
    "id": "offer_01k6gs6gxv08j8zm9zmwcq9spm",
    "url": "https://show.sandbox.toffee.com/offer_01k6gs6gxv08j8zm9zmwcq9spm",
    "status": "redeemed",
    "metadata": {
      "google-analytic-id": "your-example-id",
      "offer-placement": "game-over-screen",
      "user-tier": "free-user",
      "reward_type": "bolt-buckaroos",
      "reward_amount": "500"
    },
    "image": "https://cdn.toffee.com/offers/example.png"
  }
}

If the status code comes back as available or expired then a reward should not be issued. The user did not complete the ad offer. See the possible status codes for reference.

Possible status codes

• available: ad offer is ready to go and not yet completed
• expired: ad offers automatically expire after 24hrs and can no longer be viewed
• redeemed: user finished the ad and you should issue a reward
• consumed: reward has been issued to the user

Consume an Ad Offer

When an ad offer comes back as redeemed it means it's time to issue the reward to the user. You are expected to keep track of the reward type and amount. It's recommended to put this into the user_metadata object for easy reference.

curl --location --request PUT 'https://api-sandbox.boltapp.com/v1/gaming/beta/ad_offer/consume/YOUR_AD_OFFER_ID' \
--header 'X-API-KEY: YOUR_API_KEY' \
--header 'X-PUBLISHABLE-KEY: YOUR_PUBLISHABLE_KEY'

{
  "ad_offer_properties": {
    "id": "offer_01k6gs6gxv08j8zm9zmwcq9spm",
    "url": "https://show.sandbox.toffee.com/offer_01k6gs6gxv08j8zm9zmwcq9spm",
    "status": "consumed",
    "image": "https://cdn.toffee.com/offers/example.png"
  }
}

Enable Webhooks

To receive transaction updates in your backend, configure a webhook endpoint in your Bolt Merchant account:

• In the left-side menu, go to Administration → Webhooks.
• Enter the URL of the endpoint that will receive Bolt webhook requests.

Next Steps

You now have a working sandbox environment, an SDK installed, and your first ad integration configured.

Production

When you are done with your testing you need to get ready for production.

• Create a Production Merchant Account
• Set up your production ToffeePay account
• Swap your API keys for your production build
• Test and start accepting payments with interactive ads!