> For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt.

# Ad Event Reporting

ROIBest supports event reporting for multiple advertising platforms including Facebook, TikTok, Kwai, MgskyAds, and more. The caller does not need to distinguish which ad platform the link belongs to — ROIBest automatically routes events to the correct platform.

::: tip Channel Identification
If you need to identify which channel a link belongs to, call the [query advertising parameters](/en/developer/query-link-info.md) API and check the channel_id:

- `"4"` = Facebook
- `"5"` = Tiktok
- `"9"` = Kwai
- `"10"` = Google
- `"20"` = 小步网络
- `"21"` = OKSPIN
- `"22"` = SNAPTUBE
- `"23"` = BIGO
- `"24"` = APPLUCK
- `"34"` = Trafficstars
- `"56"` = MG SKY
- `"58"` = Macan Native
- `"60"` = Propellerads
- `"61"` = MiniTrax
  :::

Promotion links cannot be cross-posted between channels. For instance, a TikTok promotion link obtained from the MIS system cannot be placed on the Kwai platform. This will cause incorrect source identification, resulting in event feedback failures.

|        |                                                                                                                |
| :----- | :------------------------------------------------------------------------------------------------------------- |
| URL    | [https://sdk-report.roibestopenapi.com/report/fb/event](https://sdk-report.roibestopenapi.com/report/fb/event) |
| Method | POST                                                                                                           |

Before calling this API, ad configuration must be completed. Additionally, the link_id passed in the API call must be an ID generated from the ad platform.

## Request Parameters

Please use JSON format in the Request Body. The `event_name` should be set according to the event names of each advertising platform. The `extra` field's data should correspond to the required fields of each platform, and we will forward it accordingly.

| Parameter  | Type   | Required | Example Value                         | Description                                                                                          |
| :--------- | :----- | :------- | :------------------------------------ | :--------------------------------------------------------------------------------------------------- |
| link_id    | string | Yes      | 4740128923061846                      | The link ID generated by the system                                                                  |
| event_name | string | Yes      | Purchase                              | The event name obtained from the advertising platform (including custom events)                      |
| extra      | object | No       | `{"currency": "USD", "value": 19.99}` | Extra parameters for the event. ROIBest will forward them to the corresponding advertising platform. |

To determine whether extra parameters are needed, please refer to the event definitions of each advertising platform. Below are some events that require extra fields on the Facebook platform:

| English Name         | Required Fields             |
| :------------------- | :-------------------------- |
| AddToCart            | event_name                  |
| AddToWishlist        | event_name                  |
| CompleteRegistration | event_name                  |
| Contact              | event_name                  |
| Subscribe            | event_name                  |
| Purchase             | event_name, currency, value |

## Response Parameters

The response is returned in JSON format:

| Parameter | Type   | Example Value | Description                                    |
| :-------- | :----- | :------------ | :--------------------------------------------- |
| code      | int    | 0             | Status code (0 for success, non-0 for failure) |
| msg       | string | success       | Status message                                 |
| data      | object | \{}           | Additional data (if any)                       |

## Example

### Request Example

```json
{
  "link_id": "4740128923061846",
  "event_name": "Purchase",
  "extra": {
    "currency": "USD",
    "value": 19.99,
    "is_upgrade_version": 1
  }
}
```

### Response Example

```json
{
  "code": 0,
  "msg": "success",
  "data": {}
}
```

## MgskyAds Channel Notes

### Standard Event Enums

MgskyAds only recognizes the following 3 standard events. Use one of these values for `event_name`:

| Event Constant                | Description           |
| :---------------------------- | :-------------------- |
| `EVENT_COMPLETE_REGISTRATION` | Complete Registration |
| `EVENT_FIRST_DEPOSIT`         | First Deposit         |
| `EVENT_PURCHASE`              | Purchase / Payment    |

### API Event Mapping

If the `event_name` you use in API calls does not match the standard enums above (e.g. you pass `purchase`, `pay`, or `register`), you can configure **API Event Mapping rules** in ROIBest MIS → Pixel Configuration → MgskyAds → Edit dialog.

Once configured, ROIBest will automatically replace the custom `event_name` with the corresponding MgskyAds standard event before forwarding:

- **Case-insensitive** matching with automatic whitespace trimming (`Purchase`, `purchase`, `PURCHASE` are treated as identical)
- **No match**: the original `event_name` is passed through to MgskyAds as-is (not dropped, no error)
- **No mapping configured**: all events are forwarded with the original `event_name`

**Example:**

Mapping configuration (set in MIS):

| Reported Event Name | Maps to MgskyAds Standard Event |
| :------------------ | :------------------------------ |
| `purchase`          | `EVENT_PURCHASE`                |
| `pay`               | `EVENT_PURCHASE`                |
| `register`          | `EVENT_COMPLETE_REGISTRATION`   |
| `first_deposit`     | `EVENT_FIRST_DEPOSIT`           |

API request:

```json
{
  "link_id": "4740128923061846",
  "event_name": "Purchase",
  "extra": { "currency": "USD", "value": 19.99 }
}
```

Actual request forwarded to MgskyAds:

```json
{
  "link_id": "4740128923061846",
  "event_name": "EVENT_PURCHASE",
  "extra": { "currency": "USD", "value": 19.99 }
}
```