DocsGetting StartedAPI specificationAdvertisements

Advertisements

Complete guide to requesting and displaying advertisements in your game

Advertisements

After establishing authorization and creating an active game session, you can request advertisements to display to your players. This section covers the process of fetching and implementing advertisements in your game.

Prerequisites

Before requesting advertisements, ensure you have:

  1. Completed the authorization flow
  2. Established an active game session
  3. Maintained regular heartbeat requests for your session

Requesting Advertisements

POST /api/advertisements

This endpoint returns advertisement content based on available campaigns for your game.

Request Parameters

ParameterTypeRequiredDescription
game_uuidstringYesYour game's unique identifier
auth_tokenstringYesThe active authorization token from your session

Example Request

{
    "game_uuid": "32bde2de-d225-448f-8c6a-263275d93ef2",
    "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response Structure

The response contains an ad object with the following properties:

FieldTypeDescription
idnumberUnique identifier for the advertisement
titlestringAdvertisement title to display
descriptionstringBrief description of the advertisement content
typenumberDifferent formats of advertisements. Different types can have different price
campaignnumberIdentifier for the associated advertising campaign
urlstringDestination URL for user interaction with the advertisement
mediastringURL to the advertisement's media asset (image, video)
isActivebooleanIndicates if the advertisement is currently active

Example Response

{
    "ad": {
        "id": 123,
        "title": "New Season Sale!",
        "description": "Get up to 50% off on all items.",
        "type": 1,
        "campaign": 456,
        "url": "https://example.com/ad/123",
        "isActive": true,
        "media": "https://example.com/ad/123.png"
    }
}

Possible Errors

Status CodeError CodeDescription
400INVALID_IDENTIFIERThe provided game UUID is invalid
400NO_ACTIVE_SESSIONNo active session found for this user
400INVALID_TOKENThe provided authorization token is invalid
401PREMIUM_USERThe current user has premium status and should not receive advertisements
404NO_ACTIVE_CAMPAIGNSNo active advertising campaigns are available
404NO_ACTIVE_ADSNo active advertisements are available in the current campaigns
408ERR_TIMEOUTRequest timed out, try again later
500INTERNAL_SERVER_ERRORInternal server error

Implementing Advertisements

Display Guidelines

  1. User Experience: Ensure advertisements do not disrupt critical gameplay moments

  2. Tracking: Implement proper click/view tracking by directing users to the provided url when they interact with the advertisement

Premium Users

The API will return a PREMIUM_USER error code when attempting to request advertisements for users with premium status. Your implementation should:

  1. Handle this error gracefully
  2. Skip advertisement displays for premium users
  3. Continue normal game flow without waiting for advertisements

Best Practices

  1. Error Handling: Implement robust error handling to ensure the game continues functioning even if advertisement requests fail

  2. Timing: Request advertisements slightly before they are needed to account for potential network latency

  3. Testing: Thoroughly test advertisement implementation using the development UUID before deploying to production

Next Steps

After implementing advertisements, ensure your application properly maintains sessions through heartbeats and terminates sessions when users exit the game.

For additional support or integration questions, please contact our developer support team.

Session Management