# Impression Level Data

DT FairBid enables you to access detailed information for each impression through the impressions callback APIs. The information includes, for example, which demand source served the ad and its expected or exact revenue.

You can call two different APIs that refer to different stages in the impression's lifetime:

* `(OnShow)`: When the ad appears.
* `(OnAvailable)`: Before the ad appears, once a Fill becomes available.

The following table describes Impression Level Data attributes.

| Property Name         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `advertiserDomain`    | A unique identifier for a set of campaigns for the same advertiser.                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `campaignId`          | A unique identifier that represents a Campaign.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `countryCode`         | Identifier of the country of the ad impression (in ISO country code).                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `creativeId`          | <p>A unique identifier that represents the creative in the bid response.<br>This  can be useful when a particular creative causes user experience issues.</p>                                                                                                                                                                                                                                                                                                                                                                 |
| `currency`            | Currency of the payout.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `demandSource`        | <p>Identifies the demand source name of the buy-side/demand-side entity that purchased the impression:<br></p><ul><li>When mediated networks win an impression, the mediated network's name appears.</li><li>When a DSP buying through the programmatic marketplace wins the impression, the DSP's name appears.</li></ul>                                                                                                                                                                                                    |
| `impressionDepth`     | The number of impressions in the current session for the given Placement Type.                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `impressionId`        | A unique identifier for a specific impression.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `requestId`           | Unique ID of the bid request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `jsonString`          | A JSON representation of the data serialized to a String.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `netPayout`           | <p>Net payout for an impression.<br>The value accuracy is returned in the <code>priceAccuracy</code> field. The value is provided in units returned in the currency field.</p>                                                                                                                                                                                                                                                                                                                                                |
| `networkInstanceId`   | <p>The mediated ad network's original Placement/Zone/Location/Ad Unit ID that you created in their dashboard.<br>For ads shown by the DT Exchange, the <code>networkInstanceId</code> is the Placement ID you created in the DT Console.</p>                                                                                                                                                                                                                                                                                  |
| `placementType`       | <p>Defines the format and location of ads:<br></p><ul><li>Banner: Rectangle ads appear either at the top or bottom of the screen. The user can view them but cannot dismiss them.</li><li>Rewarded: Full-screen ad format that shows a short video ad to the user. Upon completion of the video, the user will earn a reward.</li><li>Interstitial: Static or video full-screen ads. The user can view and then immediately dismiss them. This is a non-rewarded format for the user.</li></ul>                               |
| `priceAccuracy`       | <p>Accuracy of the <code>netPayout</code> value:<br></p><ul><li>Programmatic: <code>netPayout</code> is the exact and committed impression value available when programmatic buyers win impressions.</li><li>Predicted: DT's estimation of the impression value is based on historical data from non-programmatic mediated network's reporting APIs.</li><li>Undisclosed: The demand source does not agree to disclose the payout of every impression; in such cases, the <code>netPayout</code> is <code>0</code>.</li></ul> |
| `renderingSDK`        | Name of the SDK in charge of rendering the ad.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `renderingSDKVersion` | <p>The version of the SDK rendering the ad.<br>When AdMob renders an impression, the <code>renderingSDKVersion</code> shows the Google Play Services version.</p>                                                                                                                                                                                                                                                                                                                                                             |
| `variantId`           | A unique identifier that represents the variant delivered to the device.                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

## Impression Data Upon Showing the Ad

All ad formats, Banners, Interstitials, and Rewarded, provide you access to the `ImpressionData` object through their callback APIs:

### Android

{% tabs %}
{% tab title="Interstitial" %}
{% code title="Kotlin" %}

```kotlin
Interstitial.setInterstitialListener(object : InterstitialListener {

    override fun onShow(placementId: String, impressionData: ImpressionData) {
        val netPayout = impressionData.netPayout
        val currency = impressionData.currency
        val priceAccuracy = impressionData.priceAccuracy
        val impressionDepth = impressionData.impressionDepth

        val message = "Placement $placementId has been shown with a " +
                      "net payout of $netPayout $currency " +
                      "with accuracy: $priceAccuracy " +
                      "and impression depth: $impressionDepth"

        Log.d(TAG, message)
    }
})

val placementId = "12345"

if (Interstitial.isAvailable(placementId)) {
    Interstitial.show(placementId, context)
}
```

{% endcode %}

Expected log output

```java
Placement 12345 has been shown with a 
net payout of 4.000000 USD 
with accuracy: PREDICTED and 
impression depth: 1
```

{% code title="Java" %}

```java
Interstitial.setInterstitialListener(new InterstitialListener() {

    @Override
    public void onShow(@NonNull String placementId, @NonNull ImpressionData impressionData) {
        double netPayout = impressionData.getNetPayout();
        String currency = impressionData.getCurrency();
        ImpressionData.PriceAccuracy priceAccuracy = impressionData.getPriceAccuracy();
        int impressionDepth = impressionData.getImpressionDepth();

        String message = String.format("Placement %s has been shown with a net payout of %f %s " +
                                       "with accuracy: %s and impression depth: %d", 
                                       placementId, netPayout, currency, priceAccuracy, impressionDepth);

        Log.d(TAG, message);
    }
});

String placementId = "12345";

if (Interstitial.isAvailable(placementId)) {
    Interstitial.show(placementId, context);
}
```

{% endcode %}

Expected log output

```java
Placement 12345 has been shown with a 
net payout of 4.000000 USD 
with accuracy: PREDICTED and 
impression depth: 1
```

{% endtab %}
{% endtabs %}

### iOS

{% tabs %}
{% tab title="Banner" %}
{% code title="Swift" %}

```swift
optional func bannerDidShow(
    _ banner: FYBBannerAdView,
    impressionData: FYBImpressionData
)
```

{% endcode %}

{% code title="Objective-C" %}

```objective-c
- (void)bannerDidShow:
    (FYBBannerAdView *)banner 
    impressionData:(nonnull FYBImpressionData *)impressionData;
```

{% endcode %}
{% endtab %}

{% tab title="Interstitial" %}
{% code title="Swift" %}

```swift
optional func interstitialDidShow(
    _ placementId: String,
    impressionData: FYBImpressionData
)

optional func interstitialDidFail(
    toShow placementId: String,
    withError error: Error,
    impressionData: FYBImpressionData
)
```

{% endcode %}

{% code title="Objective-C" %}

```objective-c
- (void)interstitialDidShow:
    (nonnull NSString *)placementId 
    impressionData:(nonnull FYBImpressionData *)impressionData;

- (void)interstitialDidFailToShow:
    (nonnull NSString *)placementId 
    withError:(nonnull NSError *)error 
    impressionData:(nonnull FYBImpressionData *)impressionData;
```

{% endcode %}
{% endtab %}

{% tab title="Rewarded" %}
{% code title="Swift" %}

```swift
optional func rewardedDidShow(
    _ placementId: String,
    impressionData: FYBImpressionData
)
optional func rewardedDidFail(
    toShow placementId: String,
    withError error: Error,
    impressionData: FYBImpressionData
)
```

{% endcode %}

{% code title="Objective-C" %}

```objective-c
- (void)rewardedDidShow:
    (nonnull NSString *)placementId 
    impressionData:(nonnull FYBImpressionData *)impressionData;
- (void)rewardedDidFailToShow:
    (nonnull NSString *)placementId 
    withError:(nonnull NSError *)error 
    impressionData:(nonnull FYBImpressionData *)impressionData;
```

{% endcode %}
{% endtab %}
{% endtabs %}

The example below showcases how to access the data on an Interstitial integration. The integration for Rewarded and Banners is similar.

{% code title="Swift" %}

```swift
func interstitialDidShow(
    _ placementId: String,
    impressionData: FYBImpressionData
) {
    let currency = impressionData.currency ?? "(nil)"
    let payout = impressionData.netPayout?.doubleValue ?? 0
    let accuracy = impressionData.priceAccuracy
    let impressionDepth = impressionData.impressionDepth
    
    print("Placement \(placementId) has been shown with a " +
          "net payout of \(payout) \(currency) " +
          "with accuracy: \(accuracy) " +
          "and impression depth: \(impressionDepth)")
}
```

{% endcode %}

{% code title="Objective-C" %}

```objective-c
- (void)interstitialDidShow:
    (NSString *)placementId 
    impressionData:(FYBImpressionData *)impressionData {
    
    NSLog(@"Placement %@ has been shown with a net payout of %@ %@ "
          "with accuracy: %d and impression depth: %i", 
          placementId, impressionData.netPayout, 
          impressionData.currency, 
          impressionData.priceAccuracy, 
          impressionData.impressionDepth);
}
```

{% endcode %}

Expected log output:

```java
Placement 12345 has been shown with a 
net payout of 4.000000 USD 
with accuracy: PREDICTED and 
impression depth: 1
```

### Unity

All ad formats provide access to the `ImpressionData` object through their callback APIs:

{% code title="C#" %}

```csharp
void OnShow(string placementId, ImpressionData impressionData); 
void OnShowFailure(string placementId, ImpressionData impressionData);
```

{% endcode %}

Example:

{% tabs %}
{% tab title="Inerstitial" %}
{% code title="C#" %}

```csharp
Interstitial.SetInterstitialListener(new MyInterstitialListener());

class MyInterstitialListener : InterstitialListener {
    public void OnShow(string placementId, ImpressionData impressionData) {
        string netPayout = impressionData.netPayout;
        string currency = impressionData.currency;
        int impressionDepth = impressionData.impressionDepth;
        ImpressionData.PriceAccuracy priceAccuracy = impressionData.priceAccuracy;

        Debug.Log($"Placement {placementId} has been shown with a " +
                  $"net payout of {netPayout} {currency} " +
                  $"with accuracy: {priceAccuracy} " +
                  $"and impression depth: {impressionDepth}");
    }
}

string placementId = "12345";

if (Interstitial.IsAvailable(placementId)) {
    Interstitial.Show(placementId);
}
```

{% endcode %}

Expected log output:

```java
Placement 12345 has been shown with a 
net payout of 4.000000 USD 
with accuracy: PREDICTED and 
impression depth: 1
```

{% endtab %}
{% endtabs %}

## Impression Data Before Showing the Ad

You can also access the same information before showing the ad. This information will be available once you have a fill for that placement. If the placement for which you request the impression data does not have a fill, the API will return `nil`.

{% hint style="warning" %}
Calling this API at different moments may result in different values for the impression depth field since impression depth is counted for the ad type, regardless of placement. For more information, see [Impression Depth](#impression-depth).
{% endhint %}

### Android

{% tabs %}
{% tab title="Banner" %}
Use this query in conjunction with loading a banner. For more information, see [Loading a Banner](https://docs.digitalturbine.com/dt-fairbid/ad-formats/banner-ads#showing-a-banner).

{% code title="Kotlin" %}

```kotlin
val bannerView = BannerView(requireContext(), placementId)
val impressionData = bannerView.impressionData
```

{% endcode %}
{% endtab %}

{% tab title="Interstitial" %}
{% code title="Kotlin" %}

```kotlin
val bannerView = BannerView(requireContext(), placementId)
val impressionData = bannerView.impressionData
```

{% endcode %}

```java
@Override
public void onAvailable(String placementId) {
    ImpressionData impressionData = Interstitial.getImpressionData(placementId);
}
```

{% endtab %}

{% tab title="Rewarded" %}
{% code title="Kotlin" %}

```kotlin
override fun onAvailable(placementId: String) {
    val impressionData = Rewarded.getImpressionData(placementId)
}
```

{% endcode %}

{% code title="Java" %}

```java
@Override
public void onAvailable(String placementId) {
    ImpressionData impressionData = Rewarded.getImpressionData(placementId);
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

### iOS

{% tabs %}
{% tab title="Interstitial" %}
{% code title="Swift" %}

```swift
func interstitialIsAvailable(_ placementId: String) {
    let impressionData = FYBInterstitial.impressionData(placementId)
}
```

{% endcode %}

{% code title="Objective-C" %}

```objective-c
@Override
- (void)interstitialIsAvailable:(NSString *)placementId {
    FYBImpressionData *impressionData = [FYBInterstitial impressionData:placementId];
}
```

{% endcode %}
{% endtab %}

{% tab title="Rewarded" %}
{% code title="Swift" %}

```swift
func interstitialIsAvailable(_ placementId: String) {
    let impressionData = FYBInterstitial.impressionData(placementId)
}
```

{% endcode %}

{% code title="Objective-C" %}

```objective-c
- (void)rewardedIsAvailable:(NSString *)placementId {
    FYBImpressionData *impressionData = [FYBRewarded impressionData:placementId];
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

### Unity

{% tabs %}
{% tab title="Insterstitial" %}
{% code title="C#" %}

```csharp
public void OnAvailable(string placementId) {
    ImpressionData impressionData = Interstitial.GetImpressionData(placementId);
}
```

{% endcode %}
{% endtab %}

{% tab title="Rewarded" %}
{% code title="C#" %}

```csharp
public void OnAvailable(string placementId) {
    ImpressionData impressionData = Rewarded.GetImpressionData(placementId);
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Impression Depth

Impression depth represents the number of impressions in a given session per ad format. Impression depth is accessible directly from each ad format class, which you can find in the following [example](#example). Alternatively, it can be accessed through the `ImpressionLevelData` object, as described in [Impression Data Upon Showing the Ad](#impression-data-upon-showing-the-a-d).

The impression depth for each ad format increases throughout the session as more ads are displayed. It is reset only when:

* The session ends (the app is killed).
* The SDK considers the session has timed out.

### Session Timeout

Session timeout or `session background timeout` represents the amount of time the user needs to spend with the app in the background before we consider them back to user engagement levels similar to a fresh new session. At this point, for all ad formats, the impression depth is reset to `0`.

The Session timeout value is 30 minutes by default.

#### Example

The example below illustrates how you can access the `impressionDepth` value for all ad formats.

{% tabs %}
{% tab title="Android" %}
{% code title="Kotlin" %}

```kotlin
val impressionDepth = Interstitial.getImpressionDepth()
      
val impressionDepth = Banner.getImpressionDepth()
      
val impressionDepth = Rewarded.getImpressionDepth()
```

{% endcode %}

{% code title="Java" %}

```java
val impressionDepth = Interstitial.getImpressionDepth()
      
val impressionDepth = Banner.getImpressionDepth()
      
val impressionDepth = Rewarded.getImpressionDepth()
```

{% endcode %}
{% endtab %}

{% tab title="iOS" %}
{% code title="Swift" %}

```swift
let impressionDepth = FYBBanner.impressionDepth

let impressionDepth = FYBInterstitial.impressionDepth

let impressionDepth = FYBRewarded.impressionDepth
```

{% endcode %}

{% code title="Objective-C" %}

```objective-c
NSUInteger impressionDepth = FYBRewarded.impressionDepth;

NSUInteger impressionDepth = FYBInterstitial.impressionDepth;

NSUInteger impressionDepth = FYBBanner.impressionDepth;
```

{% endcode %}
{% endtab %}

{% tab title="Unity" %}
{% code title="C#" %}

```csharp
int impressionDepth = Banner.GetImpressionDepth();

int impressionDepth = Interstitial.GetImpressionDepth();

int impressionDepth = Rewarded.GetImpressionDepth();
```

{% endcode %}
{% endtab %}
{% endtabs %}