### Handle AdGate Media Postbacks in PHP

Source: https://docs.adgatemedia.com/postbacks/php-postback-examples

This PHP script demonstrates how to receive postback data from AdGate Media. It includes IP address validation to ensure the data originates from AdGate Media, retrieves GET parameters, and shows examples of processing the data, such as parsing it into an object or sending notifications.

```PHP
<?php

/**
 * For a plain PHP page to receive the postback data from AdGate Media you may simply
 * retrieve the array from the global $_GET variable. To ensure that the data is coming
 * from AdGate Media check that the server sending the data is from AdGate Media by the ip
 * address as listed on your affiliate panel at http://adgatemedia.com under
 * the Postbacks Section and the Postback Information heading.
 */
define('AdGate_IP', '123.123.123.123'); // Note: as noted above change the IP to match what is in your affiliate panel.
protected $ip = $_SERVER['REMOTE_ADDR'];
protected $data = null;


/**
 * Check if the Remote Address is AdGate Media
 * if it is not throw an Exception
 */
if($ip === AdGate_IP)
{
    $data = $_GET;
    // Process or Persist Data here inline or via a function call.
} else {
    // Throw either a custom Exception or just throw a generic \Exception
    throw new InvalidIPException();
}


/**
 * The data array will contain all the macros you included under the Postbacks section of your
 * affiliate panel at http://adgatemedia.com. The array is keyed by the names you assigned to each macro
 * when you constructed the url e.g., http://yoururl.com/postback/?tx_id={transaction_id}
 * the transaction_id macro's data will have a key of 'tx_id' in the $data array: $data['tx_id'];
 *
 * Possible Macros
 * For a list of possible macros see your affiliate panel at http://adgatemedia.com under the
 * Postbacks section and the heading Postback Information.
 *
 * Parsing:
 * From the data array you may parse the data into an object, supply it to an SQL query, or do
 * any needed processing or persisting required by your application.
 *
 */

/**
 * Parse into an Object Example
 *
 * You can import the Postback data into your own custom Postback object.
 * For a simple solution you could use a Collection object to hold the Postback data,
 * if you are using a framework consider using their supplied facilities for holding and
 * persisting data. Refer to your frameworks documentation.
 */
$postback = new Postback($data);


/**
 * Processing Example
 * This example shows sending an notification to an admin when receiving a charge back of a conversion
 * being sent to the postback url.
 *
 * The example uses a Static Notify class, use your own notification class or one provided by your framework
 * of choice.
 */
if($data['status'] == 0)
{
    Notify::admin("Conversion charge back for offer " . $data['offer_id'] . " on transaction " . $data['tx_id'] . "!");
}

```

--------------------------------

### AdGateMedia LLM Configuration Schema

Source: https://docs.adgatemedia.com/publisher-apis/user-based-api-v1/get-offers

Defines the structure and purpose of configuration parameters for AdGateMedia's LLM integration, including descriptions, data types, and example values.

```APIDOC
AdGateMediaLLMConfig:
  description:
    description: "Description to display to the user"
    type: "string"
    example: "Enter to win a Playstation 5!"
  disclaimer:
    description: "A field to display with each offer. Replace the ${sitename} macro yourself."
    type: "string"
    example: "This offer is presented to you by ${sitename} on behalf of a third party merchant"
  product_id:
    description: "A unique string shared between offers which belong to same product, e.g. same mobile app."
    type: "string"
    example: "01JEEDPNV72ZX4FFY81K2HSSTC"
  product_name:
    description: "The offer's product name."
    type: "string"
    example: "Product #1"
  confirmation_time:
    description: "Text that described how long it takes to receive credit"
    type: "string"
    example: "Confirms Instantly"
  creatives:
    description: "Links to offer creatives"
    type: "object"
    example: null
    properties:
      images:
        description: "Links to offer images"
        type: "object"
        example: "{ \"275x275\": \"https://example.org/275x275.jpg\", \"400x400\": \"https://example.org/400x400.jpg\" }"
  pending_time:
    description: "Time in minutes that a reward will be held from the user following completion"
    type: "int"
    example: 60
```

--------------------------------

### Sample Offer Event Data Structure

Source: https://docs.adgatemedia.com/publisher-apis/user-based-api-v1/get-offers

An example JSON structure representing a configured offer event, including details like UUID, name, type, payout, and time-based goals.

```JSON
{
    "uuid": "7c320062-42e2-4312-95b0-ccac4904128e",
    "name": "flat_event. Complete within 1 month 2 days",
    "type": "flat",
    "payable": true,
    "event_type_id": 4,
    "ttc_minutes": 43200,
    "expires_at": 1741370829,
    "flat_points": 10,
    "flat_payout": 1,
    "flat_promotional_points": null,
    "dynamic_display_type": null,
    "dynamic_points": null,
    "dynamic_payout": null,
    "dynamic_promotional_points": null,
    "time_played": {
        "id": 996,
        "goal_unit": "MINUTES",
        "goal_unit_count": 6
    },
    "multiple_conversions_allowed": true,
    "multiple_conversions_rules": {
        "rule_type": "UNLIMITED",
        "x_conversions": null,
        "every_y_seconds": null
    }
}
```

--------------------------------

### Postback Information and Examples

Source: https://context7_llms

Details on how postbacks work and sample code for capturing them on a server.

```APIDOC
Postback Information:
  - Description: This page describes how a postback works.
  - Endpoint: /postbacks/postback-information.md

PHP Postback Examples:
  - Description: See some sample code for capturing postbacks on your server.
  - Endpoint: /postbacks/php-postback-examples.md
```

```PHP
// Example PHP code for capturing postbacks (conceptual)
<?php

// Assuming postback data is received via POST request
$offerId = $_POST['offer_id'] ?? null;
$userId = $_POST['user_id'] ?? null;
$pointsEarned = $_POST['points'] ?? 0;

if ($offerId && $userId) {
    // Process the postback data, e.g., update user points, log the event
    echo "Postback received for Offer ID: " . $offerId . ", User ID: " . $userId . ", Points: " . $pointsEarned;
    // ... your server-side logic here ...
} else {
    http_response_code(400);
    echo "Invalid postback data.";
}

?>

```

--------------------------------

### PHP PDO Postback Handling and Database Insertion

Source: https://docs.adgatemedia.com/postbacks/php-postback-examples

This PHP script demonstrates how to capture postback data from AdGate Media, validate the source IP address, and process the incoming data. It includes an inline example of inserting postback details into a MySQL database using PDO, handling potential exceptions during the database operation. The script expects postback macros to be available in the `$_GET` superglobal array.

```PHP
<?php

/**
 * For a plain PHP page to receive the postback data from AdGate Media you may simply
 * retrieve the array from the global $_GET variable. To ensure that the data is coming
 * from AdGate Media check that the server sending the data is from AdGate Media by the ip
 * address as listed on your affiliate panel at http://adgatemedia.com under
 * the Postbacks Section and the Postback Information heading.
 */
define('AdGate_IP', '123.123.123.123'); // Note: as noted above change the IP to match what is in your affiliate panel.
protected $ip = $_SERVER['REMOTE_ADDR'];
protected $data = null;
protected $servername = "localhost";
protected $username = "username";
protected $password = "password";
protected $dbname = "app";


/**
 * Check the Remote Address is AdGate Media
 * if it is not throw an Exception
 */
if($ip === AdGate_IP)
{
    $data = $_GET;
    // Process or Persist Data here inline or via a function call.
}
else {

     // Throw either a custom Exception or just throw a generic \Exception
    throw new InvalidIPException();
}


/**
 * The data array will contain all the macros you included under the Postbacks section of your
 * affiliate panel at http://adgatemedia.com. The array is keyed by the names you assigned to each macro
 * when you constructed the url e.g., http://yoururl.com/postback/?tx_id={transaction_id}
 * the transaction_id macro's data will have a key of 'tx_id' in the $data array: $data['tx_id'];
 *
 * Possible Macros
 * For a list of possible macros see your affiliate panel at http://adgatemedia.com under the
 * Postbacks section and the heading Postback Information.
 *
 * Parsing:
 * From the data array you may parse the data into an object, supply it to an SQL query, or do
 * any needed processing or persisting required by your application.
 *
 */


/**
 * Inline SQL Query Example
 */
try {
    $conn = new PDO("mysql:host=$servername;dbname=$dbname", $username, $password);
    // set the PDO error mode to exception
    $conn->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $conn->prepare("INSERT INTO Postbacks (tx_id, user_id, offer_id) VALUES (:tx_id,:user_id. :offer_id)");
    $conn->bindValue(':tx_id', $data['tx_id']);
    $conn->bindValue(':user_id', $data['user_id']);
    $conn->bindValue('offer_id', $data['offer_id']);
    // use exec() because no results are returned
    $conn->exec();
    echo "New Postback recorded successfully";
}
catch(PDOException $e)
{
    echo $sql . "<br>" . $e->getMessage();
}

$conn = null;

/**
 * Processing Example
 * This example shows sending an notification to an admin when receiving a charge back of a conversion
 * being sent to the postback url.
 *
 * The example uses a Static Notify class, use your own notification class or one provided by your framework
 * of choice.
 */
if($data['status'] == 0)
{
    Notify::admin("Conversion charge back for offer " . $data['offer_id'] . " on transaction " . $data['tx_id'] . "!");
}

```

--------------------------------

### Product Offer Schema Fields

Source: https://docs.adgatemedia.com/publisher-apis/user-based-api-v1/get-offers-by-ids

Defines the structure and properties of a product offer, including display text, identifiers, and creative assets. Each field specifies its purpose, data type, and an example value for clarity.

```APIDOC
Offer Fields Schema:

- description: Field for display text to the user.
  Type: string
  Example: "Enter to win a Playstation 5!"

- disclaimer: A field to display with each offer, allowing macro replacement (e.g., ${sitename}).
  Type: string
  Example: "This offer is presented to you by ${sitename} on behalf of a third party merchant"

- product_id: A unique string identifier shared among offers belonging to the same product (e.g., a mobile app).
  Type: string
  Example: "01JEEDPNV72ZX4FFY81K2HSSTC"

- product_name: The name of the offer's product.
  Type: string
  Example: "Product #1"

- confirmation_time: Text describing the time it takes to receive credit for an offer.
  Type: string
  Example: "Confirms Instantly"

- creatives: An object containing links to offer creatives.
  Type: object
  Example: {}
  
  - creatives.images: Links to offer images, typically keyed by image dimensions.
    Type: object
    Example: { "275x275": "https://example.org/275x275.jpg", "400x400": "https://example.org/400x400.jpg"}

- pending_time: The duration in minutes that a reward will be held before being credited to the user after completion.
  Type: int
  Example: 60
```

--------------------------------

### Offers API v2 GET Endpoint Documentation

Source: https://docs.adgatemedia.com/publisher-apis/offers-api-1

This section details the GET endpoint for the Offers API v2. It allows fetching compatible offers for virtual currency applications, requiring affiliate ID, API key, and wall code. Optional parameters enable filtering by country, payout, category, and more.

```APIDOC
Offers API (v2)

WARNING! This is our old API. Please update to [API v3](offers-api).

Use Case:
Our offers API allow you to pull offers compatible with virtual currency applications and display them natively on your website or app.
It is recommended to get a fresh list of offers every 10 minutes. Please do not use live traffic to request offers; the API should be called periodically from the backend.

Limitations:
These include:
* A page that displays user history
* Access to offers that are hyper-targeted (state or postal code specific)
* Access to thousands of market research surveys via the AdGate Rewards routing system

API:
Method: GET
Base URL: https://api.adgatemedia.com/v2/offers

Required Parameters:
- aff: Your affiliate ID. Can be found on the Offers API page. (Integer)
- api_key: Your API key. Can be found on the Offers API page. (String)
- wall_code: Wall code that can be found on the AdGate Rewards page. (String)

Optional Parameters:
- countries: Filter by specific countries. Accepts a list of comma separated country codes. (String, e.g., "gb,us,ca")
- offer: Filter by specific offers. Accepts a list of comma separated offer IDs. (String, e.g., "4849,5201,4809")
- paymin: Filter by offers above a minimum payout. Values are in USD. (Decimal, e.g., "0.50")
- minepc: Filter by offers above a minimum EPC. Values are in USD. (Decimal, e.g., "0.05")
- mobile_only: Filter by offers that can only be displayed on mobile devices. Accepted values are 1 or 0. A value of 0 will display all offers (default). (Integer, e.g., "1")
- categories: Filter by offers in certain categories. Accepts a comma separated list of category IDs. (String, e.g., "4,10,11")
- orderby: Order results by either 'payout', 'epc', or 'id'(offer id) in descending order. Default is 'epc'. (String, e.g., "payout")
- take: Limit the number of results to X. By default all results are returned. (Integer, e.g., "200")
- skip: Skips the first X number of results. Useful when combined with limiting. By default, no offers are skipped. (Integer)

Category List:
- 1: Android
- 2: Downloads
- 3: Email Submits
- 4: Free
- 10: iPad
- 11: iPhone
- 12: Lead Gen
- 13: Credit Card Required
- 14: Mobile Subscription
- 16: Surveys
- 17: Videos
- 18: CPC
- 19: Pay Per Call
- 20: Cash Back
- 21: CPI
- 22: CPE
- 23: CPA

Response:
Note that country abbreviations use the ISO standard, e.g. GB instead of UK.
```

--------------------------------

### Offer Parameters Documentation

Source: https://docs.adgatemedia.com/publisher-apis/user-based-api-v1/get-offers-by-ids

Provides a detailed breakdown of parameters used to configure offers, including mobile verification, device compatibility, and application metadata such as IDs, categories, screenshots, and video URLs.

```APIDOC
Offer Parameters:

mobile_verification_required:
  Type: bool
  Description: Whether the end user needs to verify their mobile phone number
  Default: false

web2mobile:
  Type: bool
  Description: Whether this offer must be accessed on the user's mobile device. You must send us the devices the user owns via the [POST devices] endpoints. If no devices are stored, web2mobile offers will not be returned.
  Default: FALSE

web2mobile_devices:
  Type: array|null
  Description: Array of devices the users must access the user on. NULL if not a web2mobile offer. The list of applicable devices is taken from the devices stored for that particular user (see the other devices API endpoint)
  Default: ["iphone", "ipad"]

app_metadata.app_id:
  Type: string|null
  Description: App ID on the mobile app store. It can be either App Store or Google Play Store app ID.
  Default: 1596736236

app_metadata.categories:
  Type: array|null
  Description: An array of app metadata categories.
  Default: ["Games", "Casual", "Puzzle"]

app_metadata.screenshot_urls:
  Type: array|null
  Description: An array of app metadata screenshot URLs.
  Default: ["https://is1-ssl.mzstatic.com/image/thumb/Purple126/v4/39/88/3a/39883ae6-4f45-9879-c849-aedb4d5ab40c/2e706b4c-baf0-456b-ad67-81db322f75a8_CLASSIC22_202203_2688x1242_Screenshots_01_en-US.png/643x0w.png"]

app_metadata.video_urls:
  Type: array|null
  Description: An array of app metadata video URLs.
  Default: ["https://play.google.com/video/lava/web/player/yt:movie:dSg_iqQpKYA?autoplay=1&authuser=0&embed=play"]

is_game:
  Type: bool
  Description: Whether the offer is a game offer
  Default: FALSE
```

--------------------------------

### Offer API Fields

Source: https://docs.adgatemedia.com/publisher-apis/user-based-api-v1/get-offers-by-ids

This documentation details the fields returned for an offer, including click URLs, support links, impression tracking, icons, categories, points, and promotional status. Each field specifies its purpose, data type, and an example value.

```APIDOC
Offer Object Fields:

- click_url:
  - Description: URL to redirect the user to.
  - Type: string
  - Example: https://seek.gg/vc/nQ/users/testuser/offers/360819?source_type=live_offer_api

- support_url:
  - Description: URL of the support form for this offer.
  - Type: string
  - Example: https://seek.gg/offer/contact/nqqYp2g/1666524?s1=testuser

- impression_url:
  - Description: URL to notify that the offer was viewed.
  - Type: string
  - Example: https://seek.gg/v1/user-based-api/impression?funnel_id=01JKBMPR5QYT91EGGV1R62DB2W&wall_code=nqqYp2g&user_id=testuser&offer_id=1666524

- icon_url:
  - Description: Square icon URL.
  - Type: string
  - Example: https://main-p.agmcdn.com/offers/1639000851514.jpg

- categories:
  - Description: Offer categories.
  - Type: array
  - Example: [ "CPI", "iPad", "iPhone" ]

- total_points:
  - Description: Total points the user may earn.
  - Type: float
  - Example: 126.72

- total_points_promotional:
  - Description: If a promotion is currently in progress, the amount of points they will earn. If not null, this should be used instead of total_points.
  - Type: float|null
  - Example: 187.9

- sticky:
  - Description: If an offer should be pinned to the top of the offer wall.
  - Type: bool
  - Example: TRUE
```

--------------------------------

### Offer Data Structure Example

Source: https://docs.adgatemedia.com/publisher-apis/user-based-api-v1/get-offers-by-ids

This snippet shows the typical JSON structure returned for offer data. It includes details about the offer's properties, such as its unique identifier, name, type, payout information, and conversion history.

```json
{
    "offers": [
        {
            "offer_id": 1375646,
            "name": "Complete Rank 50. Complete within 1 month 2 days",
            "type": "flat",
            "event_type_id": null,
            "payable": true,
            "ttc_minutes": 43200,
            "expires_at": 1741207121,
            "multiple_conversions_allowed": false,
            "flat_points": 100,
            "flat_payout": 10,
            "history": {
                "minutes_left": 40470.76549113333,
                "approved_conversions": 0,
                "approved_points": 0,
                "cancelled_conversions": 0,
                "cancelled_points": 0,
                "pending_conversions": 0,
                "pending_points": 0,
                "status": "viewed"
            }
        },
        {
            "offer_id": 1676274,
            "name": "Another Offer Name",
            "type": "dynamic",
            "event_type_id": 2,
            "payable": true,
            "ttc_minutes": 7200,
            "expires_at": 1741207121,
            "multiple_conversions_allowed": true,
            "dynamic_display_type": "Playtime",
            "dynamic_points": 50,
            "dynamic_payout": 5,
            "history": {
                "minutes_left": 7190.5,
                "approved_conversions": 1,
                "approved_points": 50,
                "cancelled_conversions": 0,
                "cancelled_points": 0,
                "pending_conversions": 0,
                "pending_points": 0,
                "status": "approved"
            }
        }
    ],
    "unavailable_offers": [
        {
            "offer_id": 1375646,
            "unavailable_reasons": [
                {
                    "reason": "This device or browser is not allowed [2067]",
                    "code": 2067
                }
            ]
        },
        {
            "offer_id": 1676274,
            "unavailable_reasons": [
                {
                    "reason": "Offer is inactive [2054]",
                    "code": 2054
                }
            ]
        }
    ]
}
```

--------------------------------

### Event Object Schema

Source: https://docs.adgatemedia.com/publisher-apis/user-based-api-v1/get-offers-by-ids

Describes the structure and fields of an event object. Each field includes its identifier, a description of its purpose, its data type, and an example value.

```APIDOC
Event Object:
  Represents a specific event within the system.

  Fields:
    events.#.uuid:
      - Description: Unique identifier for the event.
      - Type: string
      - Example: "0dc43f54-135a-46a4-a51c-a2c5f3cfdac0"

    events.#.name:
      - Description: The name of the event, intended for display to the user.
      - Type: string
      - Example: "Completed"

    events.#.type:
      - Description: Specifies whether the event has static point values ("flat") or varying payouts ("dynamic").
      - Type: string
      - Example: "flat"

    events.#.payable:
      - Description: Indicates whether the event awards any points or payout to the user.
      - Type: bool
      - Example: TRUE

    events.#.ttc_minutes:
      - Description: The time-to-complete for the event, measured in minutes after a user interaction (click).
      - Type: int
      - Example: 43200

    events.#.expires_at:
      - Description: A Unix timestamp indicating when the event will expire.
      - Type: int
      - Example: 1741370829

    events.#.flat_points:
      - Description: The static point value awarded for the event. Will be 0 if the event is not payable.
      - Type: float | null
      - Example: 126.72

    events.#.flat_payout:
      - Description: The static monetary payout for the event. Will be 0 if the event is not payable.
      - Type: float | null
      - Example: 46.22
```

--------------------------------

### Sample Offer Response JSON

Source: https://docs.adgatemedia.com/publisher-apis/user-based-api-v1/get-offers

A JSON object representing a sample response from an API, detailing an offer for the game Clash of Clans. It includes information like offer details, requirements, app metadata, and event tracking.

```json
{
    "data": [
        {
            "id": 1666524,
            "anchor": "Clash of Clans",
            "things_to_know": [
                "Join millions of players worldwide as you build your village, raise a clan, and compete in epic Clan Wars!",
                "You must click \u201cAllow\u201d if tracking permission is requested within the app."
            ],
            "session_hours": 720,
            "offer_expires_at": 1741370828,
            "requirements": "Join millions of players worldwide as you build your village, raise a clan, and compete in epic Clan Wars! You must click \u201cAllow\u201d if tracking permission is requested within the app.",
            "description": "Clash of Clans",
            "disclaimer": "*Points will appear as Pending for 30 days. Each person may redeem this offer only ONCE (1 time). This offer is presented to you by ${sitename} on behalf of a third party merchant or sponsor (\"Merchant\"), which advises us when the offer is completed and a reward should be issued. ${sitename} has not evaluated and does not endorse Merchant's views, policies, products or services, which you are encouraged to evaluate for yourself. Have questions? Please contact the ${sitename} Help Center.",
            "product_id": "01JEEDPNV72ZX4FFY81K2HSSTC",
            "product_name": "Product #1",
            "confirmation_time": "Confirms Instantly",
            "creatives": {
                "images": {}
            },
            "pending_time": 0,
            "is_game": true,
            "mobile_verification_required": false,
            "app_metadata": {
                "app_id": "529479190",
                "categories": [
                    "Games",
                    "Action",
                    "Entertainment",
                    "Strategy"
                ],
                "screenshot_urls": [
                    "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/04/df/6b/04df6bc3-d532-a745-a34c-47df801d8c4d/627799b5-bcad-4b62-8066-ffc4017dc4c4_clash_2208x1242_1.jpg/626x0w.jpg",
                    "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/92/5a/71/925a718f-73b4-495e-c7a6-039c4194cf76/59bd05b8-05cc-4e51-9905-7c700424b34b_clash_2208x1242_2.jpg/626x0w.jpg",
                    "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/df/34/d0/df34d02e-4609-5a42-360e-c490771fe283/f771935d-9818-48e1-8bc3-eb326d59e774_clash_2208x1242_3.jpg/626x0w.jpg",
                    "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/65/d9/0a/65d90adb-eaec-7b0d-5a72-33027b96b717/745ae951-68bc-4827-a9b5-17212cc109ed_clash_2208x1242_4.jpg/626x0w.jpg",
                    "https://is1-ssl.com/image/thumb/Purple221/v4/7a/75/73/7a757339-77aa-a8a9-0077-251432585015/a98b615c-678b-439b-83c9-323526f861d8_clash_2208x1242_5.jpg/626x0w.jpg",
                    "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/76/66/d8/7666d852-4b8b-5727-bca4-6e4278149915/bfc194c6-f848-4ed7-ae04-d37a24c00150_clash_2208x1242_6.jpg/626x0w.jpg",
                    "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/32/d9/6e/32d96e31-fdb7-17ce-845d-438f3dc7204b/9585bee6-547b-4ed0-bab6-be8ec441a0cb_clash_2208x1242_7.jpg/626x0w.jpg"
                ],
                "video_urls": []
            },
            "web2mobile": false,
            "web2mobile_devices": null,
            "click_url": "https://shortlink12.agm.mobi/vc/nqqYp2g/users/smurciac-2797-v2/offers/1666524?source_type=user_based_api&funnel_id=01JKBMPR5QYT91EGGV1R62DB2W",
            "support_url": "https://wall12.agm.mobi/offer/contact/nqqYp2g/1666524?s1=smurciac-2797-v2",
            "impression_url": "https://api12.agm.mobi/v1/user-based-api/impression?funnel_id=01JKBMPR5QYT91EGGV1R62DB2W&wall_code=nqqYp2g&user_id=smurciac-2797-v2&offer_id=1666524",
            "icon_url": "https://main-p.agmcdn.com/static/default_icon.png",
            "categories": [
                "CPI",
                "iPad",
                "iPhone"
            ],
            "sticky": true,
            "events": [
                {
                    "uuid": "a90457b6-4abf-4403-8d5f-eb4abc8ae6eb",
                    "name": "dynamic_event. Complete within 1 month 2 days",
                    "type": "dynamic",
                    "payable": true,
                    "event_type_id": null,
                    "ttc_minutes": 43200,
                    "expires_at": 1741370829,
                    "flat_points": null,
                    "flat_payout": null,
                    "flat_promotional_points": null,
                    "dynamic_display_type": "commission",
                    "dynamic_points": 10,
                    "dynamic_payout": 1,
                    "dynamic_promotional_points": null,
                    "time_played": null,
                    "multiple_conversions_allowed": true,
                    "multiple_conversions_rules": {
                        "rule_type": "UNLIMITED"
                    }
                }
            ]
        }
    ]
}
```

--------------------------------

### Offer Configuration Schema

Source: https://docs.adgatemedia.com/publisher-apis/user-based-api-v1/get-offers

Defines the parameters for configuring an offer, including its display properties, ranking logic, and associated events. This schema is used to manage offer attributes for display and user interaction.

```APIDOC
OfferConfiguration:
  sticky: bool
    Description: If an offer should be pinned to the top of the offer wall.
    Default: TRUE

  rank: int
    Description: The rank of the offer according to the "rank_method" requested.
    Default: 1

  events: array
    Description: An array of events the user may complete to earn points. Each event is an object.
    Default: [see below]

  events.#.uuid: string
    Description: ID of the event.
    Example: "0dc43f54-135a-46a4-a51c-a2c5f3cfdac0"

  events.#.name: string
    Description: Event name to display to the user.
    Example: "Completed"

  events.#.type: string
    Description: "flat" or "dynamic". Flat events have static point values. Dynamic events will have varying payouts.
    Example: "flat"

  events.#.payable: bool
    Description: Whether the event pays anything to the user.
    Default: TRUE

  events.#.ttc_minutes: int
    Description: Minutes to complete this event after the click.
    Default: 43200
```

--------------------------------

### Sample API Success Response

Source: https://docs.adgatemedia.com/publisher-apis/publisher-reporting-api

Provides an example of a successful API response containing offer data, including metrics like impressions, clicks, conversions, and payout sums, along with aggregated total columns and pagination information.

```json
{
    "data": {
        "results": [
            {
                "offer_id": 15506,
                "offer_name": "Survey Sample Savings - Burger King (US) (Incentive)",
                "is_mobile": true,
                "unique_impressions_count": 91879,
                "unique_clicks_count": 34268,
                "conversions_count": 3105,
                "payout_sum": 5589,
                "cpm": 60.83,
                "conversion_rate": 0.0906,
                "ppc": 0.16,
                "country_code": "US"
            },
            {
                "offer_id": 17192,
                "offer_name": "Lifesum iPhone Burst (US) (Incentive)",
                "is_mobile": true,
                "unique_impressions_count": 25527,
                "unique_clicks_count": 7552,
                "conversions_count": 3442,
                "payout_sum": 1652.16,
                "cpm": 64.72,
                "conversion_rate": 0.4558,
                "ppc": 0.21,
                "country_code": "US"
            }
        ],
        "totalColumns": {
            "unique_impressions_count": 117406,
            "unique_clicks_count": 41820,
            "conversions_count": 6547,
            "payout_sum": 7241.16,
            "cpm": 61.68,
            "ppc": 0.17,
            "conversion_rate": 0.1565
        },
        "paging": {
            "next": null,
            "prev": null
        }
    },
    "status": "success"
}
```

--------------------------------

### Get Offers API Endpoint

Source: https://docs.adgatemedia.com/publisher-apis/user-based-api-v1/get-offers

Fetches available offers for a user. Requires affiliate ID, API key, wall code, user ID, IP, and user agent. Supports optional parameters for filtering by rank method, subIDs, language, categories, age, gender, and device overrides.

```APIDOC
Method: GET
Base URL: https://api.adgatemedia.com/v1/user-based-api/offers

Required Query Parameters:
- aff_id (Integer): Your affiliate ID. Example: 60000
- api_key (String): Your API key. Example: 941bd1fecf7e6596823b895e04df3a0c
- wall_code (String): Wall code from the AdGate Rewards page. Example: nQug
- user_id (String): The affiliate's user ID. Max length 255 bytes. Example: user12345
- ip (String): IP v4 or v6 for geographical targeting. Example: 127.0.0.1
- user_agent (String): The end-user's user agent for device targeting. Example: Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0
- in_app (String): "true" or "false". If "true", returns offers compliant with App Store and Play Store guidelines.

Optional Parameters:
- rank_method (String): "cpm" or "cr". Determines how the rank field is calculated.
- s2, s3, s4, s5 (String): Four available subIDs to pass. Returned in postback.
- lang (String): Language code (e.g., "en-US"). Defaults to English.
- categories (String): Comma-separated app metadata categories (e.g., "game*,entertainment"). Supports partial matching with asterisk.
- exclude_categories (String): Comma-separated app metadata categories to exclude.
- is_game (String): "true" or "false". Filters for games or non-games.
- age (Integer): User's age for targeting. Example: 24
- gender (String): User's gender for targeting. Example: male
- override_w2m_devices (String): Comma-separated list of user's devices (e.g., "iphone,android"). Used if user_agent is a desktop device.
```

--------------------------------

### Event Configuration Schema

Source: https://docs.adgatemedia.com/publisher-apis/user-based-api-v1/get-offers-by-ids

Defines the structure for event configurations, including time played metrics and multiple conversion rules. This schema is used to specify how events are tracked and managed within the AdGateMedia LLM system.

```APIDOC
events:
  # Represents a specific event within the system.
  # The '#' denotes an array index or wildcard.
  # Example: events[0].time_played
  #
  time_played:
    # The unit of time that the goal is measured in.
    # Allowed values: NANOS, MICROS, MILLIS, SECONDS, MINUTES, HOURS, HALF_DAYS, DAYS, WEEKS, MONTHS, YEARS, DECADES, CENTURIES, MILLENNIA, ERAS, FOREVER.
    goal_unit: string
    # The quantity of goal unit required to complete the goal.
    goal_unit_count: integer
  #
  # Flag to indicate if an event can be converted multiple times.
  multiple_conversions_allowed: bool
  #
  # Rules governing multiple event conversions.
  # Can be UNLIMITED, TOTAL_CONVERSIONS, or INTERVAL.
  multiple_conversions_rules:
    # Type of conversion rule.
    # Allowed values: UNLIMITED, TOTAL_CONVERSIONS, INTERVAL.
    rule_type: string
    # Number of conversions allowed (used with TOTAL_CONVERSIONS or INTERVAL).
    x_conversions: int
    # Specifies the interval in seconds for the 'INTERVAL' rule type.
    # Allows X conversions every Y seconds.
    every_y_seconds: int
  #
  # Stores the history of end-user interactions with this offer event.
  history: object | null
```

--------------------------------

### AdGateMedia LLM Offer Parameters

Source: https://docs.adgatemedia.com/publisher-apis/user-based-api-v1/get-offers

Defines the parameters available for configuring AdGateMedia LLM offers, including user verification requirements, device targeting, and associated mobile application metadata.

```APIDOC
mobile_verification_required:
  description: Whether the end user needs to verify their mobile phone number.
  type: bool
  default: false
```

```APIDOC
web2mobile:
  description: Whether this offer must be accessed on the user's mobile device. You must send us the devices the user owns via the [POST devices] endpoints. If no devices are stored, web2mobile offers will not be returned.
  type: bool
  default: FALSE
```

```APIDOC
web2mobile_devices:
  description: Array of devices the users must access the user on. NULL if not a web2mobile offer. The list of applicable devices is taken from the devices stored for that particular user (see the other devices API endpoint).
  type: array|null
  default: ["iphone", "ipad"]
```

```APIDOC
app_metadata.app_id:
  description: App ID on the mobile app store. It can be either App Store or Google Play Store app ID.
  type: string|null
  default: 1596736236
```

```APIDOC
app_metadata.categories:
  description: An array of app metadata categories.
  type: array|null
  default: ["Games", "Casual", "Puzzle"]
```

```APIDOC
app_metadata.screenshot_urls:
  description: An array of app metadata screenshot URLs.
  type: array|null
  default: ["https://is1-ssl.mzstatic.com/image/thumb/Purple126/v4/39/88/3a/39883ae6-4f45-9879-c849-aedb4d5ab40c/2e706b4c-baf0-456b-ad67-81db322f75a8_CLASSIC22_202203_2688x1242_Screenshots_01_en-US.png/643x0w.png"]
```

```APIDOC
app_metadata.video_urls:
  description: An array of app metadata video URLs.
  type: array|null
  default: ["https://play.google.com/video/lava/web/player/yt:movie:dSg_iqQpKYA?autoplay=1&authuser=0&embed=play"]
```

```APIDOC
is_game:
  description: Whether the offer is a game offer.
  type: bool
  default: FALSE
```

--------------------------------

### AdGateMedia API Parameters and Categories

Source: https://docs.adgatemedia.com/publisher-apis/offers-api

This section details the optional parameters available for filtering offers via the AdGateMedia API. It includes descriptions, types, and examples for each parameter. A comprehensive list of category IDs and their corresponding names is also provided for use with the 'categories' filter.

```APIDOC
Optional Parameters:

- countries: Filter by specific countries. Accepts a list of comma separated country codes.
  Type: String
  Example: `gb,us,ca`

- offer: Filter by specific offers. Accepts a list of comma separated offer IDs.
  Type: String
  Example: `4849,5201,4809`

- paymin: Filter by offers above a minimum payout. Values are in USD.
  Type: Decimal
  Example: `0.50`

- minepc: Filter by offers above a minimum EPC. Values are in USD.
  Type: Decimal
  Example: `0.05`

- categories: Filter by offers in certain categories. Accepts a comma separated list of category IDs.
  Type: String
  Example: `4,10,11`
  Category List:
    - 1: Android
    - 2: Downloads
    - 3: Email Submits
    - 4: Free
    - 10: iPad
    - 11: iPhone
    - 12: Lead Gen
    - 13: Credit Card Required
    - 14: Mobile Subscription
    - 16: Surveys
    - 17: Videos
    - 18: CPC
    - 19: Pay Per Call
    - 20: Cash Back
    - 21: CPI
    - 22: CPE
    - 23: CPA

- platform: Filter by specific platforms. Accepts a list of comma separated platforms from this list: `desktop`, `smartphone`, `tablet`.
  Type: String
  Example: `smartphone,tablet`

- orderby: Order results by either `payout`, `epc`, or `id` (offer id) in descending order. `payout` is calculated as the maximum payout from the offer's events. Default is `epc`.
  Type: String
  Example: `payout`

- take: Limit the number of results to X. By default all results are returned.
  Type: Integer
  Example: `200`

- skip: Skips the first X number of results. Useful when combined with limiting.
  Type: Integer
  Example: (No example provided)

Response Notes:
Country abbreviations use the ISO standard, e.g. GB instead of UK.
```