OS Targeting (UAS)

Document created by pubmatic-archivist on Mar 27, 2017Last modified by catherine.racette on Aug 29, 2017
Version 6Show Document
  • View in full screen mode

Description

Use OS Targeting to target the Mobile Operating systems on Line Items. This enables targeting on specific / All Major and its minor versions.

Important Note:

  1. This API will not actually validate targetValue  ( i.e. id's for respective targeting ) provided in the POST call.  User should retrieve the valid target details using Common Mobile Operating System API and provide id's for respective targeting.
  2. User should make sure that same targetValues are not getting included / excluded at same time for same line item.

This API must be called after creating/updating Line Item successfully since it require lineitemId during targeting.

For more information about UAS Line Item Targeting Services, refer to Line Item Targeting Services (UAS)

Supported Operations 

                     

Method PathHTTP MethodDescriptionLink to Definition
/lineitems/{lineItemId}/targets/osPOSTAdd/Update/Remove OS Targeting for the Line Item LevelConfigure OS Targeting
/lineitems/{lineItemId}/targets/osGETRetrieve OS Targeting Details for a Line ItemRetrieve Targeted OS for a Line Item

 

Configure OS Targeting

 

Overview

This API enables you to add, update or remove OS Targeting for a Line Item.

 

Request

           

Request Headers

                        

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
pubTokenString${access_token}Yes

Publisher Token to authenticate and authorize the user calling the Unified Ad Server API. Send the access token generated for authentication at the place of ${access_token} in the request.

 

For more information about access tokens, refer to Getting Started with PubMatic APIs.

 

Request Body Parameters

This API accepts array of target objects, where each object must contain following attributes:

 

Parameter NameTypeRequiredValidationsDescriptions
targetLevelNumericYes

Should not be null.

Should not be empty.

You can retrieve the operating system information using information at the version level ( Major / Minor ) using targetLevel.

The following are the valid Target Levels for OS targeting:

Target LevelTargetDescriptionURL for obtaining target level list
1OS NameTo set targeting at an OS level

You can retrieve all supported OS details using following URL

http://$URI_PREFIX/api/common/mobileOS?filters=osLevel eq 1&showAll=true

2OS Major VersionOS Major Version

If you want to target at specific operating system along with all its minor version, you can retrieve the OS details with Major version as follows.

E.g. Retrieving the Major versions of iOS. You have passosTypeId as filter received in osLevel eq 1 request. 

http://$URI_PREFIX/api/common/mobileOS?filters=osLevelEQ 2&filters=osTypeId EQ 1&pageNumber=1&sort=verMajor

3OS Minor VersionOS Minor Version

If you want to target at specific set of minor version for given operating system and its major version, you can retrieve the OS details with minor version as follows.

E.g. You want to target the line item on Android 3.2, Android 3.3. You have pass osTypeId as filter received in osLevel eq 2 request. 

http://$URI_PREFIX/api/common/mobileOS?filters=osLevelEQ 3&filters=osTypeId EQ 2&filters=verMajor EQ 3

targetValueNumberic

Yes

Should not be null.

Should not be empty.

Target Value can contain the actual or reference identifier. Expect to provide the id received from /common/mobileOS/ API.

The following are supported data types:

Target TypeTarget Value Data TypeReference/Actual Value
OS NameNumericReference Value.  id attribute from the response returned by/common/mobileOS/ API
OS Major VerseionNumericReference Value.  id attribute from the response returned by/common/mobileOS/ API
OS Minor VersionNumericReference Value.  id attribute from the response returned by/common/mobileOS/ API
excludeBooleanYes

Default will be false.

Valid values can be true or false.

This value indicates whether the OS is to be included / excluded while targeting the Line Item

Sample Request URL

https://api.pubmatic.com/v1/uas/ineitems/{lineItemId}/targets/os/

 

Sample Request JSON

Include the iOS as targeting but exclude the iOS Manjor version 1,2,3

{
    "targets": [{
        "targetValue": 6,
        "targetLevel": 1
    }, {
        "targetValue": 5,
        "targetLevel": 2,
        "exclude": true
    }, {
        "targetValue": 4,
        "targetLevel": 2,
        "exclude": true
    }, {
        "targetValue": 3,
        "targetLevel": 2,
        "exclude": true
    }]
}

 

Sample Request JSON: Remove OSTargeting for a LIne Item

{
     "targets": []
}

Response

Sample Response JSON

{
     "entity": {
         "id": {targetid associated with lineitem},
         "isPreset": 0
     },
     "targets": [{
         "targetValue": 6,
         "exclude": false,
         "targetLevel": 1,
         "osTypeId": 1,
         "osName": "iOS"
     }, {
         "targetValue": 5,
         "exclude": true,
         "targetLevel": 2,
         "osTypeId": 1,
         "osName": "iOS 1",
         "verMajor": "1"
     }, {
         "targetValue": 4,
         "exclude": true,
         "targetLevel": 2,
         "osTypeId": 1,
         "osName": "iOS 2",
         "verMajor": "2"
     }, {
         "targetValue": 3,
         "exclude": true,
         "targetLevel": 2,
         "osTypeId": 1,
         "osName": "iOS 3",
         "verMajor": "3"
     }]
}

 

Retrieve Targeted OS for a Line Item

 

Overview

This API enables you to Retrieve OS Targeting for a Line Item.

Request

Request Headers

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
pubTokenString${access_token}Yes

Publisher Token to authenticate and authorize the user calling the Unified Ad Server API. Send the access token generated for authentication at the place of ${access_token} in the request.

 

For more information about access tokens, refer to Getting Started with PubMatic APIs.

Request Body Parameters

This API accepts array of target objects, where each object must contain following attributes:

 

Parameter NameTypeRequiredValidationsDescriptions
targetLevelNumericYes

Should not be null.

Should not be empty.

You can retrieve the operating system information using information at the version level ( Major / Minor ) using targetLevel.

The following are the valid Target Levels for OS targeting:

Target LevelTargetDescriptionURL for obtaining target level list
1OS NameTo set targeting at an OS level

You can retrieve all supported OS details using following URL

http://$URI_PREFIX/api/common/mobileOS?filters=osLevel eq 1&showAll=true

2OS Major VersionOS Major Version

If you want to target at specific operating system along with all its minor version, you can retrieve the OS details with Major version as follows.

E.g. Retrieving the Major versions of iOS. You have passosTypeId as filter received in osLevel eq 1 request. 

http://$URI_PREFIX/api/common/mobileOS?filters=osLevelEQ 2&filters=osTypeId EQ 1&pageNumber=1&sort=verMajor

3OS Minor VersionOS Minor Version

If you want to target at specific set of minor version for given operating system and its major version, you can retrieve the OS details with minor version as follows.

E.g. You want to target the line item on Android 3.2, Android 3.3. You have pass osTypeId as filter received in osLevel eq 2 request. 

http://$URI_PREFIX/api/common/mobileOS?filters=osLevelEQ 3&filters=osTypeId EQ 2&filters=verMajor EQ 3

targetValueNumberic

Yes

Should not be null.

Should not be empty.

Target Value can contain the actual or reference identifier. Expect to provide the id received from /common/mobileOS/ API.

The following are supported data types:

Target TypeTarget Value Data TypeReference/Actual Value
OS NameNumericReference Value.  id attribute from the response returned by/common/mobileOS/ API
OS Major VerseionNumericReference Value.  id attribute from the response returned by/common/mobileOS/ API
OS Minor VersionNumericReference Value.  id attribute from the response returned by/common/mobileOS/ API
excludeBooleanYes

Default will be false.

Valid values can be true or false.

This value indicates whether the OS is to be included / excluded while targeting the Line Item

Sample Request URL

https://api.pubmatic.com/v1/uas/lineitems/{lineItemId}/targets/devicecapabilities/ 

Response

Sample Response JSON

{
     "targets": [{
         "targetValue": 6,
         "exclude": false,
         "targetLevel": 1,
         "osTypeId": 1,
         "osName": "iOS"
     }, {
         "targetValue": 5,
         "exclude": true,
         "targetLevel": 2,
         "osTypeId": 1,
         "osName": "iOS 1",
         "verMajor": "1"
     }, {
         "targetValue": 4,
         "exclude": true,
         "targetLevel": 2,
         "osTypeId": 1,
         "osName": "iOS 2",
         "verMajor": "2"
     }, {
         "targetValue": 3,
         "exclude": true,
         "targetLevel": 2,
         "osTypeId": 1,
         "osName": "iOS 3",
         "verMajor": "3"
     }]
}

 

Error Codes for OS Targeting

Error codes will be displayed with row information. Row indicates the order of the target object in the request.

 

Sr. NoError CodesError MessageDescription
1PH_ACCESS_DENIEDAccess DeniedWhen the lineitemid provided does not exist or you don't have access to a line item to perform the edit operation.
2PH_MISSING_OR_INVALID_PARAMETERMissing or Invalid Target ValueWhen any target object contains NULL or an empty target value
3PH_MISSING_OR_INVALID_PARAMETERMissing or Invalid entity id [id] When an invalid Line Item Id is provided in the request
4PH_DUPLICATE_ENTRIES_FOUNDDuplicate targets targetValue [id]When any targetValue is duplicated during the POST request
 

 

 

Unified Ad Server References

Common Request Query Parameters for Web Services

Supported Operations for Filters

HTTP Status Codes

Unified Ad Server Specific Error Codes

 

Version 0.1

Attachments

    Outcomes