Understanding Domain Models

Abstract

Describes the domain model mappings and key object differences for advertisers who are migrating from Yahoo Native APIs to Yahoo DSP APIs.

Domain Model Mappings

The diagram below illustrates the mappings (color-coded for better understanding) that specify the associations and differences in domain models when migrating from Native to DSP.

domain model mapping

Note the differences in naming conventions and where the attributes reside for each of the objects shown.

Native API (High-Level View)

The Native domain model, as shown, is based on four core objects or entity types in the Native stack:

  • Advertiser

  • Campaign

  • AdGroup

  • Ad

Each object has its own endpoint with methods for creating, updating and retrieving ad data, and is defined in the section below.

Advertiser

The Advertiser object, for example, provides methods for retrieving advertiser data.

https://api.gemini.yahoo.com/v3/rest/advertiser/

An advertiser is an entity that manages campaigns in the Yahoo Native API. It has settings such as contact information and billing details, and is able to manage campaigns and view reports for those campaigns.

Campaign

Provides methods for creating, updating, deleting and retrieving campaigns. You can also create an app install campaign if your goal is to generate app downloads. A campaign organizes one or more ad groups together and has its own budget and targeting settings. Campaigns allow you to manage your ads based on your advertising goals and business strategy.

Endpoint:

https://api.gemini.yahoo.com/v3/rest/campaign/

AdGroup

Provides methods for creating, updating, and retrieving ad groups. An ad group is a collection of ads and targeting objects that is associated with a particular campaign.

Endpoint:

https://api.gemini.yahoo.com/v3/rest/adgroup

DSP API (High-Level View)

With DSP, the domain model changes. By comparison to Native, there are six core objects in the DSP stack, with objects that correlate to similar objects in Native. The notable exception is the DSP Campaign object, which has no correlative to a Native Campaign.

Each of the six objects is defined in the section below.

Advertiser

A company that lists advertisements on DSP to purchase inventory provided by a range of publishers in the broader marketplace. A seat holder manages direct advertisers.

Campaign

An advertising goal that defines a strategy for delivering ads within a set time period. You set up a campaign by defining its flight dates, budgets, frequency caps, demographic targeting data provider, and campaign goals.

Endpoint:

/traffic/campaign

Package

Provides advertisers with a level of organization and the added benefit of budget allocation to a Campaign.

Under a Campaign, you can create one or more packages, which hold specific budgets, flight dates, and an objective. Each Package contains one or more Lines, which enable you to define your targeting types. While a package is live, it allocates its budget automatically across the lines within it, which simplifies budgeting.

Line

A subcomponent of a Campaign that specifies an advertising strategy. DSP defines each line by one or more ads, a goal type, and a set of budgetary and targeting parameters. Each line item represents a distinct targeting strategy.

Endpoint:

/traffic/lines

Targeting

Line-level targeting provides rules to specify how ads served by a line are delivered to consumers. Lines can target specific exchanges, deals, locations, demographics, ad positions, frequency, audiences, devices, days of the week, apps, URLs, page relevancy, mobile carriers, and languages.

Endpoint:

/traffic/targeting

Ad

A creative that is linked to a line item and ready to serve on a web page. You use standard HTTP methods GET, POST and PUT to read/create/update ads.

Creative

An object that defines the image or video asset that is the foundation of an ad. The creative identifies the file type (image or video file), the advertising environment (native or web), and the file hosting information (Yahoo or a third-party).

You use standard POST and PUT methods to add/update new display, video, or audio creatives.

Endpoint:

/traffic/creatives

Bid Multiplier

A line-level resource that that specifies the relative weight that should be given to targeted ad placement opportunities.

Endpoint:

/traffic/lines/<lineId>/bidmultipliers

Associations & Differences

Some of the key associations and differences (color-coded) between the Native and the DSP domain models:

  • A Native Campaign associates with a Package in DSP.

  • An AdGroup in Native associates with a Line.

  • DSP supports a creative library. A creative be associated with a line for it to serve. This relationship is called an Ad. A creative can be associated with multiple lines.

  • While Native has a generic targeting model composed of type, value and bid modifier, DSP has explicit endpoints for every single targeting type, and distinct attributes associated with these endpoints.

  • A Native advertiser has to take Native targeting objects and fan them out to many different types in DSP.

  • A bid modifier is its own separate object in DSP, and not an attribute.

  • A Campaign maps to a Package where you have a budget schedule, which is half-yellow, and half-green in the color coding of the diagram. The Package gets the budget (yellow) from Campaign, then the green, which is the schedule from AdGroup: it’s a blend of both of those two attributes.

  • Frequency cap is first class object on Native, but an attribute on DSP.

  • The billing method in DSP has no representation in Native.