Skip to content

Preflight Checks

Beta

Joining the Beta

Preflight checks are currently in beta. To join the beta program, please contact your Publisher Support Advocate.

Overview

AdGem has implemented a new preflight check mechanism for offer links. This feature allows publishers to verify the status of an offer before redirecting users to the click_url, thus improving user experience by avoiding dead or irrelevant links.

How It Works

  1. Retrieve the click_url from any of AdGem’s API as usual.
  2. Before redirecting the user, send a HEAD request to this click_url from the user's device.
  3. Our system will return a status code indicating whether it's safe to redirect the user.
  4. Based on the status code, you can decide whether to show the offer to the user or take alternative actions. AdGem will only provide the status code, so you can custom craft the message to show your users where applicable.

HTTP Status Codes

The preflight check will return one of the following status codes:

  • 200 OK: The offer is active and the user meets all targeting criteria. It's safe to redirect the user.
  • 403 Forbidden: The user does not meet the targeting criteria for this offer, or the user or publisher is suspended.

Note

A store_id eligibility check is performed automatically during the preflight check and doesn't require any additional action from Publishers. It is recommended for Publishers to implement their own store_id filtering for more comprehensive control. One method for collecting the store_id from AdGem can be via Player Event Postbacks.

  • 404 Not Found: The offer is not currently active or no longer exists.
  • 422 Unprocessable Entity: The request is invalid.

Implementation

To use this feature:

  • Use the click_url you received from AdGem’s API.
  • Instead of immediately redirecting the user with a GET request, first send a HEAD request to this URL.
  • Check the HTTP status code in the response.
  • Allow the user to proceed to the click_url if you receive a 200 OK status.
  • For other status codes, you may want to remove the offer from the user's view or try fetching a new offer.

Important

The AdGem response to the HEAD request will never have a body, only a status code!

Resources

  • External resources on HEAD checks: HEAD - HTTP | MDN

  • AdGem URL example: https://api.adgem.com/v1/click

Examples

Successful Scenario

  • Parameters: appid=456&playerid=test035&platform=android&os_version=10.0.0&cid=4560
  • Response: Http-Status Response: 200
  • Content: No content

A 200 response means that an offer is active and available. It is safe to redirect the Player to the click_url for them to begin the offer.

Error Scenario

  • Parameters: appid=example&playerid=test035&platform=android&os_version=10.0.0&cid=456
  • Response: Http-Status Response: 422
  • Content: No content

A 422 response indicates that the request is invalid since the appid must be both an integer and a valid appid in the AdGem system.

Error Scenario

  • Parameters: appid=456&playerid=test035&platform=android&os_version=10.0.0&cid=456
  • Response: Http-Status Response: 404
  • Content: No content

A 404 response indicates that even though appid and cid are valid for the AdGem system, the offer is not currently active or no longer exists.

Additional Information

  • The store_id eligibility check is only performed for HEAD requests and may not apply to all requests or all publishers.

  • Publishers are encouraged to maintain their own store_id filtering mechanisms for more comprehensive control over offer eligibility.

Updated on August 7, 2024