New to v201204 of DFP API are
custom fields, which can be applied to
orders,
line items, and
creatives. This new feature gives you the ability to include additional information on DFP entities without having to implement data persistence in your own system. They are saved when the entities are saved on the DFP servers which ensures data consistency and removes the need for syncing.
Data Types
The following are the supported
data types of a custom field:
- String
- Number
- Toggle (true/ false)
- Drop-down (selection from user-defined values)
These data types should cover some of the most common use cases for custom fields such as comments (string), metrics (number), and internal system status (toggle/drop-down).
How-To
You can create and manage your custom fields and
custom field options (for drop-down custom fields) with the new
CustomFieldService. Please make sure you have the feature enabled for your network before you try to set up custom fields. We are also working on bringing custom fields to the user interface, so be on the lookout for them!
Walk-Through
The following Java sample shows how you can add a string and drop-down custom field value to your line item. This assumes that you have already created the custom fields and custom field options. You can check out how to create them using the
CreateCustomFields and
CreateCustomFieldOptions examples in the
client libraries.
Long customFieldId = Long.parseLong("INSERT_STRING_CUSTOM_FIELD_ID_HERE");
Long dropDownCustomFieldId =
Long.parseLong("INSERT_DROP_DOWN_CUSTOM_FIELD_ID_HERE");
Long customFieldOptionId =
Long.parseLong("INSERT_CUSTOM_FIELD_OPTION_ID_HERE");
Long lineItemId = Long.parseLong("INSERT_LINE_ITEM_ID_HERE");
// Get the line item.
LineItem lineItem = lineItemService.getLineItem(lineItemId);
// Create custom field values.
List customFieldValues = new ArrayList();
// Create the String custom field value.
TextValue textValue = new TextValue();
textValue.setValue("Custom field value");
CustomFieldValue customFieldValue = new CustomFieldValue();
customFieldValue.setCustomFieldId(customFieldId);
customFieldValue.setValue(textValue);
customFieldValues.add(customFieldValue);
// Create the drop-down custom field value.
DropDownCustomFieldValue dropDownCustomFieldValue =
new DropDownCustomFieldValue();
dropDownCustomFieldValue.setCustomFieldId(dropDownCustomFieldId);
dropDownCustomFieldValue.setCustomFieldOptionId(customFieldOptionId);
customFieldValues.add(dropDownCustomFieldValue);
// The line item can contain custom field values for the field you are
// trying to set or an unrelated one. The following checks that you only
// add existing custom field values for custom fields different from the
// ones you are setting.
if (lineItem.getCustomFieldValues() != null) {
for (BaseCustomFieldValue oldCustomFieldValue :
lineItem.getCustomFieldValues()) {
if (!oldCustomFieldValue.getCustomFieldId().equals(customFieldId)
&& !oldCustomFieldValue.getCustomFieldId().equals(
dropDownCustomFieldId)) {
customFieldValues.add(oldCustomFieldValue);
}
}
}
// Set the custom field values on the line item.
lineItem.setCustomFieldValues(customFieldValues.toArray(
new BaseCustomFieldValue[]{}));
// Update the line item on the server.
LineItem[] lineItems = lineItemService.updateLineItems(
new LineItem[] {lineItem});
And that’s it! For the full Java code example, you can refer to the
SetLineItemCustomFieldValue in the client library.
With this new feature, we aim to help you create stronger integrations with DFP through the API. If there are any features you would like us to demonstrate, please don’t hesitate to let us know with a
forum post or at a
Office Hour Hangout.
- Jeffrey Sham, DFP API Team
- Kevin Winter, AdWords API Team
- Joseph DiLallo, DFA API Team
