Device Capability Targeting

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

Description

Use Device Capability Targeting to target the line item on features supported by Mobile Devices.

Important Note:

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

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/devicecapabilitiesPOSTAdd/Update/Remove Device Capabilities for the Line ItemAdd/Update/Remove Device Capability Targeting
/lineitems/{lineItemId}/targets/devicecapabilitiesGETRetrieve Device Capability Details for a Line ItemRetrieve Targeted Device Capabilities for a Line Item

 

 

Add/Update/Remove Device Capability Targeting

Overview

This API enables you to add, update or remove Device Capability 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

                               

Parameter NameTypeRequiredValidationsDescriptions
targetLevelNumericYes

Should not be null.

Should not be empty.

Device Capability has only a single target level.

               
Target LevelTargetDescriptionURL for obtaining target level list
1Device CapabilityDevice Capability Targeting

You can retrieve the supported device capabilities for targeting using the following URL. You can apply sorting on supported dimensions.

http://$URI_PREFIX/api/common/devicecapability?dimensions=id,name&sort=id

targetValueNumberic

Yes

Should not be null.

Should not be empty.

Target Value can contain the actual or reference value. It will depend on which target level you are targeting for.

e.g. If you want to target for device capability NFC support then targetValue = 6
 

The following are supported data types:

             
Target TypeTarget Value Data TypeReference/Actual Value
Device CapabilityNumericReference Value.  id attribute from the response returned by http://$URI_PREFIX/api/common/devicecapability
excludeBooleanYes

Default will be false.

Valid values can be true or false.

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

Sample Request URL

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

Sample Request JSON

    

{
    "targets": [
        {
            "targetValue": 1,
            "targetLevel": 1,
            "exclude": false
        },
        {
            "targetValue": 5,
            "targetLevel": 1,
            "exclude": false
        },
        {
            "targetValue": 6,
            "targetLevel": 1,
            "exclude": false
        }
    ]
}

Sample Request JSON: Remove Device Capability Targeting

{
    "targets": []
}

Response

Sample Response JSON

    

{
    "entity": {
        "id": {targetid associated with lineitem},
        "isPreset": 0
    },
    "targets": [{
        "targetValue": 1,
        "exclude": false,
        "targetLevel": 1,
        "deviceCapabilityId": 1,
        "deviceCapabilityName": "Phone calls"
    }, {
        "targetValue": 5,
        "exclude": false,
        "targetLevel": 1,
        "deviceCapabilityId": 5,
        "deviceCapabilityName": "Touchscreen support"
    }, {
        "targetValue": 6,
        "exclude": false,
        "targetLevel": 1,
        "deviceCapabilityId": 6,
        "deviceCapabilityName": "NFC support"
    }]
}

 

Retrieve Targeted Device Capabilities for a Line Item

Overview

This API enables you to retrieve Device Capability 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

                               

Parameter NameTypeRequiredValidationsDescriptions
targetLevelNumericYes

Should not be null.

Should not be empty.

Device Capability has only a single target level.

               
Target LevelTargetDescriptionURL for obtaining target level list
1Device CapabilityDevice Capability Targeting

You can retrieve the supported device capabilities for targeting using the following URL. You can apply sorting on supported dimensions.

http://$URI_PREFIX/api/common/devicecapability?dimensions=id,name&sort=id

targetValueNumberic

Yes

Should not be null.

Should not be empty.

Target Value can contain the actual or reference value. It will depend on which target level you are targeting for.

e.g. If you want to target for device capability NFC support then targetValue = 6
 

The following are supported data types:

             
Target TypeTarget Value Data TypeReference/Actual Value
Device CapabilityNumericReference Value.  id attribute from the response returned by http://$URI_PREFIX/api/common/devicecapability
excludeBooleanYes

Default will be false.

Valid values can be true or false.

This value indicates whether the device capability 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": 1,
        "exclude": false,
        "targetLevel": 1,
        "deviceCapabilityId": 1,
        "deviceCapabilityName": "Phone calls"
    }, {
        "targetValue": 5,
        "exclude": false,
        "targetLevel": 1,
        "deviceCapabilityId": 5,
        "deviceCapabilityName": "Touchscreen support"
    }, {
        "targetValue": 6,
        "exclude": false,
        "targetLevel": 1,
        "deviceCapabilityId": 6,
        "deviceCapabilityName": "NFC support"
    }]
}

Error Codes for Device Capability 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