Ad Experience

This guide will help you fetch metrics and dimensions used to compile Smartsight Ad Experience dashboards.

Percentage of Ad Fill Rate GET

Returns the percentage number of ads served divided by the total number of ad requests that the server makes

curl 'https://smartsight3.mediamelon.com/mm-apis/session/<customer-id>?planlevel=<level>&period=start=1729666800,end=1730271600&metrics=adfillrate,player&agg=1&aggby=player'
-x GET --header 'Authorization: Bearer <access_token>'

If you run this request yourself it will not work, you should replace the <access_token> in this example with your own Keycloak access_token you get by running Fetch Auth Token

Required request path parameters

customer-id string

A path parameter in form of a string. This is the unique identifier and you will be able to find this Id on your user profile page.

Required request query parameters

planlevelstring

A query parameter in form of a string. This is the plan identifier number associated with CustomerID and you will be able to find this plan level using https://smartsight.mediamelon.com/planLevelByCustId/<customer-id>

period string

A query parameter in comma-separated string format. It needs to in the format of start date and end date (eg: start=1729666800,end=1730271600) in epoch time. For reference, use this Epoch Time converter

metricsstring

Combination of query parameters metrics=adfillrate,playerin string format. This request needs comma-separated metrics to retrieve the rquested data.

agg string

A query parameter in form of a string to return data by enabling or disabling aggregation (values: 1 or 2).

aggby string

A query parameter in form of a string. The requested data will aggregated by given dimension query parameter.

Response

GET 200

{
    "totalcount": 17,
    "pagecount": 17,
    "totalrecords": 17,
    "response": [
        {
            "adfillrate": 100.0,
            "player": "tve-web-theo",
            "totalpages": 17
        },
        .
        ..
        ...
        ....,
        {
            "adfillrate": 0.0,
            "player": "svod-ios-avplayer",
            "totalpages": 17
        }
    ]
}

---

Number of Ad Impression GET

Returns the total number of times an ad is displayed on user's screen, regardless of whether the users interacted with it

curl 'https://smartsight3.mediamelon.com/mm-apis/session/<customer-id>?planlevel=<level>&period=start=1729666800,end=1730271600&metrics=adimpression,player&agg=1&aggby=player'
-x GET --header 'Authorization: Bearer <access_token>'

Required request path parameters

customer-id string

A path parameter in form of a string. This is the unique identifier and you will be able to find this Id on your user profile page.

Required request query parameters

planlevelstring

A query parameter in form of a string. This is the plan identifier number associated with CustomerID and you will be able to find this plan level using https://smartsight.mediamelon.com/planLevelByCustId/<customer-id>

period string

A query parameter in comma-separated string format. It needs to in the format of start date and end date (eg: start=1729666800,end=1730271600) in epoch time. For reference, use this Epoch Time converter

metricsstring

Combination of query parameters metrics=adimpression,playerin string format. This request needs comma-separated metrics to retrieve the rquested data.

agg string

A query parameter in form of a string to return data by enabling or disabling aggregation (values: 1 or 2).

aggby string

A query parameter in form of a string. The requested data will aggregated by given dimension query parameter.

Response

GET 200

{
    "totalcount": 17,
    "pagecount": 17,
    "totalrecords": 17,
    "response": [
        {
            "adimpression": 3,
            "player": "tve-web-theo",
            "totalpages": 17
        },
        .
        ..
        ...
        ....,
        {
            "adimpression": 17,
            "player": "svod-ios-avplayer",
            "totalpages": 17
        }
    ]
}

---

Number of Ad Play GET

Returns total number of times an ad impression was actually seen by users

curl 'https://smartsight3.mediamelon.com/mm-apis/session/<customer-id>?planlevel=<level>&period=start=1729666800,end=1730271600&metrics=adplay,player&agg=1&aggby=player'
-x GET --header 'Authorization: Bearer <access_token>'

Required request path parameters

customer-id string

A path parameter in form of a string. This is the unique identifier and you will be able to find this Id on your user profile page.

Required request query parameters

planlevelstring

A query parameter in form of a string. This is the plan identifier number associated with CustomerID and you will be able to find this plan level using https://smartsight.mediamelon.com/planLevelByCustId/<customer-id>

period string

A query parameter in comma-separated string format. It needs to in the format of start date and end date (eg: start=1729666800,end=1730271600) in epoch time. For reference, use this Epoch Time converter

metricsstring

Combination of query parameters metrics=adplay,playerin string format. This request needs comma-separated metrics to retrieve the rquested data.

agg string

A query parameter in form of a string to return data by enabling or disabling aggregation (values: 1 or 2).

aggby string

A query parameter in form of a string. The requested data will aggregated by given dimension query parameter.

Response

GET 200

{
    "totalcount": 17,
    "pagecount": 17,
    "totalrecords": 17,
    "response": [
        {
            "adplay": 3,
            "player": "tve-web-theo",
            "totalpages": 17
        },
        .
        ..
        ...
        ....,
        {
            "adplay": 17,
            "player": "svod-ios-avplayer",
            "totalpages": 17
        }
    ]
}

---

Number of Ad Errors GET

Returns total number of times an ad error occurred during an ad's lifecycle

curl 'https://smartsight3.mediamelon.com/mm-apis/session/<customer-id>?planlevel=<level>&period=start=1729666800,end=1730271600&metrics=aderror,player&agg=1&aggby=player'
-x GET --header 'Authorization: Bearer <access_token>'

Required request path parameters

customer-id string

A path parameter in form of a string. This is the unique identifier and you will be able to find this Id on your user profile page.

Required request query parameters

planlevelstring

A query parameter in form of a string. This is the plan identifier number associated with CustomerID and you will be able to find this plan level using https://smartsight.mediamelon.com/planLevelByCustId/<customer-id>

period string

A query parameter in comma-separated string format. It needs to in the format of start date and end date (eg: start=1729666800,end=1730271600) in epoch time. For reference, use this Epoch Time converter

metricsstring

Combination of query parameters metrics=aderror,playerin string format. This request needs comma-separated metrics to retrieve the rquested data.

agg string

A query parameter in form of a string to return data by enabling or disabling aggregation (values: 1 or 2).

aggby string

A query parameter in form of a string. The requested data will aggregated by given dimension query parameter.

Response

GET 200

{
    "totalcount": 17,
    "pagecount": 17,
    "totalrecords": 17,
    "response": [
        {
            "aderror": 2,
            "player": "tve-web-theo",
            "totalpages": 17
        },
        .
        ..
        ...
        ....,
        {
            "aderror": 4,
            "player": "svod-ios-avplayer",
            "totalpages": 17
        }
    ]
}

---

Number of Ad Block GET

Total number of times an ad was blocked

curl 'https://smartsight3.mediamelon.com/mm-apis/session/<customer-id>?planlevel=<level>&period=start=1729666800,end=1730271600&metrics=adblock,player&agg=1&aggby=player'
-x GET --header 'Authorization: Bearer <access_token>'

Required request path parameters

customer-id string

A path parameter in form of a string. This is the unique identifier and you will be able to find this Id on your user profile page.

Required request query parameters

planlevelstring

A query parameter in form of a string. This is the plan identifier number associated with CustomerID and you will be able to find this plan level using https://smartsight.mediamelon.com/planLevelByCustId/<customer-id>

period string

A query parameter in comma-separated string format. It needs to in the format of start date and end date (eg: start=1729666800,end=1730271600) in epoch time. For reference, use this Epoch Time converter

metricsstring

Combination of query parameters metrics=adblock,playerin string format. This request needs comma-separated metrics to retrieve the rquested data.

agg string

A query parameter in form of a string to return data by enabling or disabling aggregation (values: 1 or 2).

aggby string

A query parameter in form of a string. The requested data will aggregated by given dimension query parameter.

Response

GET 200

{
    "totalcount": 17,
    "pagecount": 17,
    "totalrecords": 17,
    "response": [
        {
            "adblock": 1,
            "player": "tve-web-theo",
            "totalpages": 17
        },
        .
        ..
        ...
        ....,
        {
            "adblock": 0,
            "player": "svod-ios-avplayer",
            "totalpages": 17
        }
    ]
}

---

Ad Startup Delay GET

Average time taken by ads to start playing back

curl 'https://smartsight3.mediamelon.com/mm-apis/session/<customer-id>?planlevel=<level>&period=start=1729666800,end=1730271600&metrics=adlatency'
-x GET --header 'Authorization: Bearer <access_token>'

Required request path parameters

customer-id string

A path parameter in form of a string. This is the unique identifier and you will be able to find this Id on your user profile page.

Required request query parameters

planlevelstring

A query parameter in form of a string. This is the plan identifier number associated with CustomerID and you will be able to find this plan level using https://smartsight.mediamelon.com/planLevelByCustId/<customer-id>

period string

A query parameter in comma-separated string format. It needs to in the format of start date and end date (eg: start=1729666800,end=1730271600) in epoch time. For reference, use this Epoch Time converter

metricsstring

Combination of query parameters metrics=adlatencyin string format. This request needs comma-separated metrics to retrieve the rquested data.

Response

GET 200

{
    "totalcount": 1,
    "pagecount": 1,
    "totalrecords": 1,
    "response": [
        {
            "adlatency": 983.6793103448276,
            "viewercount": 465250,
            "totalpages": 1
        }
    ]
}

---

Percentage of Ad Buffering Ratio GET

Returns percentage of ad viewing time spent in buffering

curl 'https://smartsight3.mediamelon.com/mm-apis/session/<customer-id>?planlevel=<level>&period=start=1729666800,end=1730271600&metrics=adbufferingratio,player,adviewtime&agg=1&aggby=player'
-x GET --header 'Authorization: Bearer <access_token>'

Required request path parameters

customer-id string

A path parameter in form of a string. This is the unique identifier and you will be able to find this Id on your user profile page.

Required request query parameters

planlevelstring

A query parameter in form of a string. This is the plan identifier number associated with CustomerID and you will be able to find this plan level using https://smartsight.mediamelon.com/planLevelByCustId/<customer-id>

period string

A query parameter in comma-separated string format. It needs to in the format of start date and end date (eg: start=1729666800,end=1730271600) in epoch time. For reference, use this Epoch Time converter

metricsstring

Combination of query parameters metrics=adbufferingratio,player,adviewtime in string format. This request needs comma-separated metrics to retrieve the rquested data.

agg string

A query parameter in form of a string to return data by enabling or disabling aggregation (values: 1 or 2).

aggby string

A query parameter in form of a string. The requested data will aggregated by given dimension query parameter.

Response

GET 200

{
    "totalcount": 17,
    "pagecount": 17,
    "totalrecords": 17,
    "response": [
        {
            "adbufferingratio": 0.00669494930947873,
            "player": "svod-tvos-avplayer",
            "adviewtime": 0.0,
            "playdur": 6508582.0,
            "totalpages": 17
        },
        .
        ..
        ...
        ....
        {
            "adbufferingratio": 0.0532,
            "player": "svod-ios-avplayer",
            "adviewtime": 0.0,
            "playdur": 18125257.0,
            "totalpages": 17
        }
    ]
}

---

Exit Before Ad Starts GET

Average time taken by ads to start playing back

curl 'https://smartsight3.mediamelon.com/mm-apis/session/<customer-id>?planlevel=<level>&period=start=1729666800,end=1730271600&metrics=adstartupabandonmentrate'
-x GET --header 'Authorization: Bearer <access_token>'

Required request path parameters

customer-id string

A path parameter in form of a string. This is the unique identifier and you will be able to find this Id on your user profile page.

Required request query parameters

planlevelstring

A query parameter in form of a string. This is the plan identifier number associated with CustomerID and you will be able to find this plan level using https://smartsight.mediamelon.com/planLevelByCustId/<customer-id>

period string

A query parameter in comma-separated string format. It needs to in the format of start date and end date (eg: start=1729666800,end=1730271600) in epoch time. For reference, use this Epoch Time converter

metricsstring

Combination of query parameters metrics=adstartupabandonmentratein string format. This request needs comma-separated metrics to retrieve the rquested data.

Response

GET 200

{
    "totalcount": 1,
    "pagecount": 1,
    "totalrecords": 1,
    "response": [
        {
            "adstartupabandonmentrate": 3.226294427952345,
            "attempts": 490028,
            "failurerate": 3.4618429967267175,
            "totalpages": 1
        }
    ]
}

---

Percentage of Ad Buffering Ratio GET

Returns percentage of ad viewing time spent in buffering

curl 'https://smartsight3.mediamelon.com/mm-apis/session/<customer-id>?planlevel=<level>&period=start=1729666800,end=1730271600&metrics=adskippercentage,player&agg=1&aggby=player'
-x GET --header 'Authorization: Bearer <access_token>'

Required request path parameters

customer-id string

A path parameter in form of a string. This is the unique identifier and you will be able to find this Id on your user profile page.

Required request query parameters

planlevelstring

A query parameter in form of a string. This is the plan identifier number associated with CustomerID and you will be able to find this plan level using https://smartsight.mediamelon.com/planLevelByCustId/<customer-id>

period string

A query parameter in comma-separated string format. It needs to in the format of start date and end date (eg: start=1729666800,end=1730271600) in epoch time. For reference, use this Epoch Time converter

metricsstring

Combination of query parameters metrics=adskippercentage,player in string format. This request needs comma-separated metrics to retrieve the rquested data.

agg string

A query parameter in form of a string to return data by enabling or disabling aggregation (values: 1 or 2).

aggby string

A query parameter in form of a string. The requested data will aggregated by given dimension query parameter.

Response

GET 200

{
    "totalcount": 17,
    "pagecount": 17,
    "totalrecords": 17,
    "response": [
        {
            "adskippercentage": 0.8,
            "player": "tve-web-theo",
            "totalpages": 17
        },
        .
        ..
        ...
        ....
        {
            "adskippercentage": 0.1,
            "player": "svod-tvos-avplayer",
            "totalpages": 17
        }
    ]
}

---

Percentage of CTR GET

Returns percentage of ads that were clicked by the user

curl 'https://smartsight3.mediamelon.com/mm-apis/qbrData/session/<customer-id>?planlevel=<level>&period=start=1729666800,end=1730271600&metrics=adclickthroughrate,player&agg=1&aggby=player'
-x GET --header 'Authorization: Bearer <access_token>'

Required request path parameters

customer-id string

A path parameter in form of a string. This is the unique identifier and you will be able to find this Id on your user profile page.

Required request query parameters

planlevelstring

A query parameter in form of a string. This is the plan identifier number associated with CustomerID and you will be able to find this plan level using https://smartsight.mediamelon.com/planLevelByCustId/<customer-id>

period string

A query parameter in comma-separated string format. It needs to in the format of start date and end date (eg: start=1729666800,end=1730271600) in epoch time. For reference, use this Epoch Time converter

metricsstring

Combination of query parameters metrics=adclickthroughrate,player in string format. This request needs comma-separated metrics to retrieve the rquested data.

agg string

A query parameter in form of a string to return data by enabling or disabling aggregation (values: 1 or 2).

aggby string

A query parameter in form of a string. The requested data will aggregated by given dimension query parameter.

Response

GET 200

{
    "totalcount": 17,
    "pagecount": 17,
    "totalrecords": 17,
    "response": [
        {
            "adclickthroughrate": 0.14415054145215694,
            "player": "tve-android-exoplayer",
            "totalpages": 17
        },
        .
        ..
        ...
        ....
        {
            "adclickthroughrate": 1.15054145215694,
            "player": "tve-tvos-avplayer",
            "totalpages": 17
        }
    ]
}

---