# Interactive Ads Quickstart
> Interactive Ads Quickstart
Source: https://help.boltapp.com/gaming/guide/interactive-ads/quickstart
⏱️ 15-minute integration
Bolt Gaming has partnered with [ToffeePay](https://docs.toffee.com/) 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](/gaming/guide/interactive-ads/quickstart#create-a-bolt-sandbox-account)
* [Install an SDK](/gaming/guide/interactive-ads/quickstart#install-an-sdk)
* [Get Your API Keys](/gaming/guide/interactive-ads/quickstart#get-your-api-keys)
* [Create Personalized Ad Offer](/gaming/guide/interactive-ads/quickstart#create-personalized-ad-offer)
* [Enable Webhooks](/gaming/guide/interactive-ads/quickstart#enable-webhooks)
Review the [Process Flow Overview](/gaming/guide/process-flow-overview) page to see how the overall end-to-end integration flow works.
## Create a Bolt Sandbox Account [#create-a-bolt-sandbox-account]
If you don't have one, create a [Bolt Merchant Sandbox account](https://merchant-sandbox.boltapp.com/onboarding/get-started/gaming) 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](https://merchant-sandbox.boltapp.com/).
## Install an SDK [#install-an-sdk]
We provide lightweight SDKs to help you get started:
* [JavaScript SDK](/gaming/platforms/javascript/intro/overview) · [GitHub](https://github.com/BoltApp/bolt-frontend-sdk)
More SDKs are coming soon for Unity and other platforms.
### Usage [#usage]
Use the SDK to display interactive ads with `BoltSDK.gaming.openAd()`. Here's a sample implementation:
```javascript title="JavaScript"
// 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](https://show.sandbox.toffee.com/offer_01k5y8wdbk5b390mmwdz5ja7cd)
## Get Your API Keys [#get-your-api-keys]
Once you create a [Bolt Merchant account](https://merchant-sandbox.boltapp.com/), [sign in](https://merchant-sandbox.boltapp.com/) 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
```bash title="Bash"
--header 'X-API-KEY: YOUR_API_KEY' \
--header 'X-PUBLISHABLE-KEY: YOUR_PUBLISHABLE_KEY' \
```
## Create Personalized Ad Offer [#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.
```bash title="Request"
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"
}'
```
```json title="Response"
{
"id": "offer_01k6gs6gxv08j8zm9zmwcq9spm",
"url": "https://show.sandbox.toffee.com/offer_01k6gs6gxv08j8zm9zmwcq9spm",
"status": "available",
"image": "https://cdn.toffee.com/offers/example.png",
"expires": 3600
}
```
#### Metadata [#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.
```bash title="Request"
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"
}
}'
```
```json title="Response"
{
"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 [#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.
```bash title="Request"
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:
```json title="Response"
{
"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
Once an ad offer is finished by the user it will automatically be marked as redeemed by our system. It will stay in that state until consumed (see next section on how to do that). Redeemed ad offers cannot expire so you can rely on that status to know when to issue rewards to the user.
## Consume an Ad Offer [#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.
```bash title="Request"
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'
```
```json title="Response"
{
"ad_offer_properties": {
"id": "offer_01k6gs6gxv08j8zm9zmwcq9spm",
"url": "https://show.sandbox.toffee.com/offer_01k6gs6gxv08j8zm9zmwcq9spm",
"status": "consumed",
"image": "https://cdn.toffee.com/offers/example.png"
}
}
```
You can only consume redeemed ad offers. You will get an error if you try to consume an offer with any other status. Ensure you mark an offer as consumed only after issuing the reward to the user. There is no way to set the status back.
## Enable Webhooks [#enable-webhooks]
To receive transaction updates in your backend, configure a webhook endpoint in your [Bolt Merchant account](https://merchant-sandbox.boltapp.com/):
* In the left-side menu, go to **Administration** → **Webhooks**.
* Enter the URL of the endpoint that will receive Bolt webhook requests.
See how to [Validate Webhook Authenticity](/gaming/guide/bolt-webhooks/validate-authenticity) in the Bolt Webhooks.
## Next Steps [#next-steps]
You now have a working sandbox environment, an SDK installed, and your first ad integration configured.
### Production [#production]
When you are done with your testing you need to get ready for production.
* [Create a Production Merchant Account](https://merchant.boltapp.com/onboarding/get-started/gaming)
* Set up your production ToffeePay account
* Swap your API keys for your production build
* Test and start accepting payments with interactive ads!