> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adrop.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Reference

> Class, interface, constant, and type definitions for Adrop Web SDK.

## Classes

### Adrop

The main SDK class. Works as a singleton.

#### Static Methods

| Method            | Return Type | Description                                      |
| ----------------- | ----------- | ------------------------------------------------ |
| `observe(config)` | `Adrop`     | Initialize SDK and start automatic DOM detection |
| `instance()`      | `Adrop`     | Return existing instance                         |

#### Instance Methods

| Method                          | Return Type                 | Description                    |
| ------------------------------- | --------------------------- | ------------------------------ |
| `renderAd(container, request?)` | `Promise<void>`             | Render ad                      |
| `requestAd(request)`            | `Promise<AdropAdResponse>`  | Request ad data only (single)  |
| `requestAds(request)`           | `Promise<AdropAdsResponse>` | Request multiple ads data only |
| `clear(container)`              | `void`                      | Remove ad                      |
| `setConfig(config)`             | `void`                      | Update configuration           |
| `on(event, callback, filter?)`  | `void`                      | Register event listener        |
| `off(event, callback)`          | `void`                      | Unregister event listener      |

#### Instance Properties

| Property  | Type           | Description                            |
| --------- | -------------- | -------------------------------------- |
| `uid`     | `string`       | User identifier (getter/setter)        |
| `appKey`  | `string`       | API authentication key (getter/setter) |
| `metrics` | `AdropMetrics` | User property management               |

### AdropMetrics

User property management class.

#### Methods

| Method                     | Return Type     | Description                                                    |
| -------------------------- | --------------- | -------------------------------------------------------------- |
| `setUserProperties(props)` | `AdropMetrics`  | Set user properties (chainable)                                |
| `setAppProperties(props)`  | `AdropMetrics`  | Set app properties (chainable)                                 |
| `commit()`                 | `Promise<void>` | Save properties to server                                      |
| `properties()`             | `Properties`    | Return currently set properties (user + app + device)          |
| `clear()`                  | `void`          | Clear user and app properties (device properties are retained) |

***

## Interfaces

### AdropConfig

SDK initialization options.

```typescript theme={null}
interface AdropConfig {
  appId: string;             // App ID (required)
  uid?: string;              // User identifier
  appKey?: string;           // API authentication key
  debug?: boolean;           // Debug logging (default: false)
  backfillMode?: BackfillMode; // Global backfill rendering mode (1.2.3+, default: 'responsive')
}
```

### AdropAdRequest

Ad request parameters.

```typescript theme={null}
interface AdropAdRequest {
  unit: string;              // Unit ID (required)
  uid?: string;              // User identifier
  contextId?: string;        // Contextual targeting ID
  trackMode?: 0 | 1;         // 0: auto, 1: manual (native)
  isEntireClick?: boolean;   // Entire area click (native)
  theme?: AdTheme;           // Theme
  useCustomClick?: boolean;  // Custom click handling
  backfillMode?: BackfillMode; // Per-slot backfill rendering mode override (1.2.3+)
  adId?: string;             // Advertising identifier — required for View on Device preview
}
```

<Note>
  `adId` is the advertising identifier used by the **View on Device** feature to preview a draft creative on a registered test device. See the [Preview Creatives on Test Device](/management/support#preview-creatives-on-test-device) guide for setup. Do not ship to production with `adId` hard-coded.
</Note>

### AdropAdResponse

Ad response object (single ad).

```typescript theme={null}
interface AdropAdResponse {
  code: AdropErrorCode;  // Response code
  msg: string;           // Response message
  result?: AdData;       // Ad data (on success)
}
```

### AdropAdsResponse

Ad response object (multiple ads).

```typescript theme={null}
interface AdropAdsResponse {
  code: AdropErrorCode;  // Response code
  msg: string;           // Response message
  results?: AdData[];    // Ad data array (on success)
}
```

### AdData

Ad data object.

```typescript theme={null}
interface AdData {
  // Common
  format: AdFormat;       // Ad format
  unit: string;           // Unit ID
  ad: string;             // Ad HTML content
  w: number;              // Ad width
  h: number;              // Ad height
  type?: string;          // Ad type
  target?: string;        // Target URL open method

  // Native ad fields
  headline?: string;      // Ad title
  body?: string;          // Ad description
  callToAction?: string;  // CTA button text
  asset?: string;         // Main image URL
  destinationURL?: string; // Click destination URL

  // Identifier fields
  id?: string;            // Ad ID
  cpId?: string;          // Campaign ID
  creativeId?: string;    // Creative ID
  accountTag?: string;    // Account-level tag
  creativeTag?: string;   // Creative-level tag

  // Tracker fields (trackMode=1)
  pixelTracker?: string;  // Pixel tracker URL (1x1 image for impression)
  imprTracker?: string;   // Impression tracker URL
  clickTracker?: string;  // Click tracker URL

  // Advertiser profile
  profile?: {
    displayLogo?: string;  // Advertiser logo URL
    displayName?: string;  // Advertiser name
    link?: string;         // Advertiser profile link
  };

  // Extra text items
  extra?: Record<string, string>;
}
```

### AdropEventFilter

Event filter options.

```typescript theme={null}
interface AdropEventFilter {
  unit?: string;  // Filter specific unit only
}
```

***

## Constants

### Adrop.Events

Event constants. Access via `Adrop.Events`.

| Constant              | Value                | Description               |
| --------------------- | -------------------- | ------------------------- |
| `AD_RECEIVED`         | `'adReceived'`       | Ad received successfully  |
| `AD_NO_FILL`          | `'adNoFill'`         | No direct ads             |
| `AD_IMPRESSION`       | `'adImpression'`     | Ad impression             |
| `AD_CLICKED`          | `'adClicked'`        | Ad click                  |
| `AD_FAILED`           | `'adFailed'`         | Ad request failed         |
| `AD_BACKFILL_NO_FILL` | `'adBackfillNoFill'` | No backfill ads           |
| `AD_VIDEO_START`      | `'adVideoStart'`     | Video ad playback started |
| `AD_VIDEO_END`        | `'adVideoEnd'`       | Video ad playback ended   |

### Adrop.ErrorCode

Error codes. Access via `Adrop.ErrorCode`.

| Constant                    | Value  | Description         |
| --------------------------- | ------ | ------------------- |
| `OK`                        | `0`    | Success             |
| `ERROR_CODE_INVALID_UNIT`   | `4000` | Invalid unit ID     |
| `ERROR_CODE_AD_INACTIVE`    | `4001` | No active campaigns |
| `ERROR_CODE_AD_NO_FILL`     | `4002` | No matching ads     |
| `ERROR_CODE_INVALID_PARAMS` | `4003` | Invalid parameters  |

***

## Types

### AdFormat

Ad format type.

```typescript theme={null}
type AdFormat = 'banner' | 'nativeAd' | 'backfill';
```

### AdTheme

Theme type.

```typescript theme={null}
type AdTheme = 'light' | 'dark';
```

### BackfillMode

Backfill ad rendering mode type. (SDK 1.2.3+)

```typescript theme={null}
type BackfillMode = 'responsive' | 'fixed';
```

See the [Backfill Rendering Mode](/sdk/web/backfill) guide for behavior and selection criteria.

***

## Event Callbacks

Callback signatures for each event.

```typescript theme={null}
// Ad received, impression, click
type AdReceivedCallback = (unit: string, adData: AdData) => void;
type AdImpressionCallback = (unit: string, adData: AdData) => void;
type AdClickedCallback = (unit: string, adData: AdData) => void;

// No ad, failed, backfill no fill
type AdNoFillCallback = (unit: string) => void;
type AdFailedCallback = (unit: string) => void;
type AdBackfillNoFillCallback = (unit: string) => void;

// Video
type AdVideoStartCallback = (unit: string, adData: AdData) => void;
type AdVideoEndCallback = (unit: string, adData: AdData) => void;
```

<Note>
  All event callbacks receive `unit` as the first argument. Events `AD_RECEIVED`, `AD_IMPRESSION`, `AD_CLICKED`, `AD_VIDEO_START`, and `AD_VIDEO_END` also receive `adData` as the second argument.
</Note>