Transcription
Campaign Management APIfor News PublishersAdvertising on Apple News November 2021Version 3.0
ContentsGetting Started .4Authentication and Access .4Convert PEM Certificate .5Versioning .5Endpoints .5InitSession .6Formatting Requests .7Responses .7Limitations .7Campaign and Line Metadata .8GetAvailableCampaignCategories .9GetTargetingDetails .11Sensitive Topics Opt-in/Opt-out .11Geotargeting .11v1 attribute .13GetSegments .14Deprecated Segment .15GetAvailableTimeZones .16GetLineInfo .17GetAllChannels .18Campaign and Line Creation and Management .19CreateCampaign .20CreateLine .23UpdateCampaign.32UpdateLine .35DeleteCampaign .44DeleteLine .45Inventory .46Campaign Management APIfor News PublishersNovember 20212
CheckLineInventory .47CheckInventory.52ReserveInventory .59UnreserveInventory .61Reporting Metadata .62GetCampaignSummary .63GetCampaignDetails .68GetLineDetails .72Reporting Metrics Methods .76GetCampaignMetrics .76GetLineMetrics .79GetLinePerformance .83GetLinePerformanceByChannel .85Appendix A: Line Type, Creative Type, and Ad Position Values .87Appendix B: Values per Supported IAB Format .90Validations .90Release Notes .91Campaign Management APIfor News PublishersNovember 20213
Getting StartedThe Campaign Management API for News Publishers is available to all Apple Newspublisher accounts with access to News Publisher tools on Workbench. You can use yourtools and programs of choice to manage ad campaigns programmatically. With the API,you can do the following. Create and manage ad campaigns on Apple News. Retrieve performance metrics for ad campaigns. Estimate the availability of inventory for ad placements on Apple News.The API generally follows the functionality and workflow of Workbench. If you are newto the API, start with familiarizing yourself with Workbench functionality to gain contextwhen utilizing the API.Authentication and AccessAuthentication is the first step in utilizing the Campaign Management API for NewsPublishers.An access token provides authorization to all functionality of the API. To access theApple News Ads API server, request and download the required API keys, tokens, andcertificate from Workbench.1. Click on the dropdown arrow next to your account name near the top right and selectAccount from the dropdown menu.2. Select the API tab under the page title.3. Click Create Key.4. Name your key and select Publisher Inventory Campaigns.5. Enter the Captcha text.6. Confirm and download your key in a ZIP file, containing the following files. certificate.pem : a client-side SSL certificate signed by Apple Ad Platforms. private key.key : a client-side SSL private key token.txt : an access tokenCampaign Management APIfor News PublishersNovember 20214
Convert PEM CertificateThe downloaded certificate is a PEM file. The following commands use the publiclyavailable openssl and keytool utilities to convert the PEM certificate to P12 or JKSformats as needed.1. Convert your PEM-format certificate to a P12-format certificate.openssl pkcs12 -export -in certificate.pem -inkey private key.key-out certificate.p12 -name " name "2. Convert the P12-format certificate to a JKS-format certificate.keytool -v -importkeystore -srckeystore certificate.p12 -srcstoretypePKCS12 -destkeystore certificate.jks -deststoretype JKSVersioningThe current version of the Campaign Management API for News Ad Publishers is v3.Backward compatibility is not supported. Campaigns and lines that are created using v3cannot be read and updated using v1 endpoints.EndpointsUse the following endpoint URL: paign Management APIfor News PublishersNovember 20215
InitSessionInitSession authenticates your account, establishes a secure connection, andprovides the sessionId required to make additional API calls. InitSession must becalled before every API interaction session to obtain a sessionId that will be used withall subsequent calls during the session. A SessionId expires after one hour ofinactivity.Resource URLPOST cessToken accesstoken InitSession Example Payload{"method": "InitSession","id": "Request-012345","params": {"accessToken": " accessToken "},"jsonrpc": "2.0"}CallInitSessionDescriptionCall InitSession to initiate access and get a criptionStringYesThe accessToken is one of the keys given to auser along with client side certificate to initiatea ionThe SessionId that needs to be used for all other APIoperations.InitSession is the only call in the API that does not return a Success value.Important: as a security measure, ten successive invalid authentication attempts willlock the API access for a minimum of five hours.Campaign Management APIfor News PublishersNovember 20216
Formatting RequestsThe API supports JSON-RPC 2.0 payloads over HTTP POST. Communication with theweb service must use HTTPS. To make requests, use the Content-Type header of application/json. The request payload contains the method name and the method parameters, which isa single dictionary object. Request objects must follow the JSON-RPC 2.0 specification and must include thefollowing fields: jsonrpc: A string specifying the version of JSON-RPC protocol. The string valuemust be exactly 2.0. method: A string containing the name of the method to be invoked. Id: A unique identifier established by your client program. It must be a string thatis unique for each call. The server will reply back using the same ID. The outputresponse will be uniquely associated with the call that generated it. params: An array of name-value pairs of named parameters and theircorresponding values.Responses A response is a JSON-RPC 2.0 payload in a HTTP response with the Content-Typeheader of “application/json” encoded as UTF-8. The response payload contains the result, which will be a single dictionary object. Response objects follow the JSON-RPC 2.0 specification and include the followingfields: jsonrpc: A string specifying the version of JSON-RPC protocol, which isexactly 2.0. Id: This will be provided in every response and is the same as the ID sent inthe request object. result: a result attribute is a boolean value of true or false indicatingsuccess or failure of the API call. If Success is true, then result includes theresponse to the method request. If Success is false, then result includes anerror message and an error code.LimitationsThere is a limit of 10,000 API calls in UTC, per 24 hours, total for the CampaignManagement API for News Publishers.Campaign Management APIfor News PublishersNovember 20217
Campaign and Line MetadataUse metadata to fetch parameters and values to use in when you create a campaignand create a line.Method NameGetAvailableCampaignCategoriesDescriptionThe method to get a complete list of available CategoryIdsand category information.GetTargetingDetailsThe method to get a detailed list of all line targetingparameters.GetSegmentsThe method to get a list of audience segments.GetAvailableTimeZonesThe method to get a list of valid time zones.GetLineInfoThe method to get information available about all lines in acampaign.GetAllChannelsThe method to get information available about all channelsthat may be used in a campaign.See also inventory methods for metadata to manage your inventory. Use reportingmetadata to measure the results of your campaigns.Resource URLPOST https://iadapi.apple.com/publisher/campaigns/v3In the request payload, use a method name.{"method": " method name ","id": "Request123","params": {"SessionId": " SessionId "},"jsonrpc": "2.0"}Campaign Management APIfor News PublishersNovember 20218
GetAvailableCampaignCategoriesUse GetAvailableCampaignCategories to retrieve an exhaustive list of category andsubcategory names that can be used for campaign targeting. TheGetAvailableCampaignCategories method requires only your SessionId as input.GetAvailableCampaignCategories Input escriptionSessionId obtained from InitSession call.GetAvailableCampaignCategories Example Request Payload{"method": "GetAvailableCampaignCategories","id": "Request123","params": {"SessionId": pc": "2.0"}GetAvailableCampaignCategories Output ParametersParameterCategoryCategory: CategoryIdTypeCollectionDescriptionA collection of 3-tuples, each containingCategoryId, CategoryName, andSubCategoryName.Numeric String The Id of the category.Category: CategoryNameStringThe name of the category.Category: SubCategoryNameStringThe name of the subcategory.SuccessCampaign Management APIfor News PublishersBoolean(true/false)Can be true or false depending onwhether the call succeeded or not.November 20219
Response SubCategoryName":"Business to Business iness to Business (B2B)"}],[{"SubCategoryName":"Beauty & "CPG"},Apply targeting dimensions using CreateLine and UpdateLine. Ads in categories areserved within specific channel feeds. If no categories are in input, then ads serve in allcategories.Campaign Management APIfor News PublishersNovember 202110
GetTargetingDetailsThe GetTargetingDetails method allows you to retrieve all possible targetingparameters to use when creating a line. Apply targeting dimensions using CreateLineand UpdateLine.Sensitive Topics Opt-in/Opt-outSensitive Topics Opt-in/Opt-out is currently a Workbench feature at the line level. Theability to opt-in or opt-out of sensitive topics in a campaign is not yet available throughthe Campaign Management API for News Publishers. Lines edited in Workbench thatuse sensitive topics cannot be edited through the API. Lines edited in the API cannotuse the sensitive topics feature in Workbench.GeotargetingCurrently, the API for News Publishers supports country code US geotargeting by Stateand DesignatedMarketArea. If you use geotargeting for Canada, Australia, or GreatBritain, continue to use Workbench for managing your campaigns. Geotargetingsupport in Workbench has broader coverage for state and city equivalents in Canada(province), Australia (state and postal), and Great Britain (country/crown dependency).Lines created in Workbench with geotargeting parameters other than country code USare unsupported through the API.GetTargetingDetails Input he SessionId is obtained from theInitSession call.CountryCodeStringYesTwo-character code of a country. Acceptedvalues are AU, CA, GB, or US. Geotargetingmetadata is available for US only.Numeric StringYesThe Id of the campaign. To retrieve aCampaignId, use ngDetails Example Request Payload{"method": "GetTargetingDetails","id": "Request-012345","params": {"SessionId": yCode": "US","CampaignId":"15598796"},"jsonrpc": "2.0"}Campaign Management APIfor News PublishersNovember 202111
GetTargetingDetails Output ensions:TypeCollectionConsists of two parts, a country and alist of dimensions, each containing aDimensionName and aNameValueList.StringTwo-character code of a country.Accepted values are AU, CA, GB, or US.Geotargeting details are available forUS only.CollectionEach element of Dimensions containsa DimensionName and aNameValueList.StringNames the contents of the dimensionin question.List of Name andValue pairsAssociates code numbers and codenames with value strings to define thecontents of the dimension.CollectionConsists of two parts, a country and alist of Dimensions, each containing aDimensionName and TargetingDimensionsDescriptionDimensionName: DeviceStringA NameValueList of device typesavailable for use with Lines:CreativeType. See Values perSupported IAB Format.DimensionName: AgeRangeStringA NameValueList of age ranges.DimensionName: GenderStringA NameValueList of gender choices.DimensionName: StatesStringA NameValueList of U.S. StatesDimensionName:StringA NameValueList of supported U.S.market areas.StringA NameValueList of days available.DesignatedMarketAreaDimensionName: DaysCampaign Management APIfor News PublishersNovember 202112
DimensionName: ChannelsCollectionAn array of the channels IDs owned bythe publisher. Each name-and-valuepair consists of a name part which isthe channel UUID and a value partconsisting of a Name parameter and aSections parameter, where each of theSections has name-and-value pairssimilar to the NameValueList of theother Dimensions.Channels: Channel UUIDStringChannel UUID, identifying thecorresponding Name and Sections.Note, there is no parameter nameassociated with this value.Channels: NameStringChannel Name per channel UUID.There is only one channel, feedFCSubscribedTopStories. For thisinitial channel, there are no sections.ListList of name-value pairs per channelUUID.Boolean(true/false)Can be true or false depending onwhether the call succeeded or not.Channels: SectionsSuccessv1 attributeParameterDimensionName: SlotsTypeDescriptionStringA NameValueList of specific hour slots available.Note: slots are only available with v1 endpoints."TargetingDimensions": ECOND"],Campaign Management APIfor News PublishersNovember 202113
GetSegmentsUse GetSegments to determine your available audience segment types. Applegenerates publisher audience segment data based on users who read or follow yourcontent on Apple News. Segment availability is determined by your org, not bycampaign or line.GetSegments Input ParametersThe GetSegments method requires only your SessionId as iptionSessionId obtained from InitSession call.GetSegments Example Request 47465415ddddb406a3f95c90267286d3"}}Campaign Management APIfor News PublishersNovember 202114
GetSegments Output onA collection of Id-value pairs.SegmentIdStringThe Id of the segment.SegmentNameStringThe name of the segment.SegmentTypeStringThe type of segment.ChannelInclude or exclude users who have shown specificinterest in your content on Apple News through readingyour content or following your channels.Publication SubscriptionSelected publishers can include or exclude users whohave subscribed to their content via Apple News.NotificationsEnables you to target users who have opted-in to receivenotifications. You have the option to include and/orexclude Publisher Audience Segments.SegmentSizeStringEstimated segment size or N/A.DeveloperNameStringIdentifies the owner of an app. This parameter is notapplicable to News Publisher segment types.SuccessBooleanCan be true or false depending on whether the call(true/false) succeeded or not.Deprecated SegmentCustom audience segments is no longer available in the Campaign Management API forNews Publishers. Custom audience segments includes first party data (phone, email,IDFA) you own and that has been uploaded through My Audiences in Workbench.Campaign Management APIfor News PublishersNovember 202115
GetAvailableTimeZonesUse GetAvailableTimeZones to retrieve a list of time zone names that can be used tospecify campaign scheduling.The GetAvailableTimeZones method requires only your SessionId as input.GetAvailableTimeZones Input escriptionSessionId obtained from InitSession call.GetAvailableTimeZones Example Request Payload{"method": "GetAvailableTimeZones","id": "Request-012345","params": {"SessionId": pc": "2.0"}GetAvailableTimeZones Output ParametersParameterTypeSupportedTimeZonesArray ListSuccessCampaign Management APIfor News PublishersDescriptionAn array list of all the time zones supported andapplicable country.BooleanCan be true or false depending on whether the(true/false) call succeeded or not.November 202116
GetLineInfoThe method to retrieve information available about line types, creative types, and adpositions.GetLineInfo Input dStringYesSessionId obtained from InitSession call.CampaignIdStringYesThe Id of the campaign. This determines whetherthe data returned is for House line types or Direct. Toretrieve a CampaignId, use GetCampaignSummary.GetLineInfo Example Request Payload{"method": "GetLineInfo","id": "Request-012345","params": {"SessionId": gnId": "15598796"},"jsonrpc": "2.0"}GetLineInfo Output st of available line types.CreativeTypesList of MapsMaps of LineTypes to an array of allowed creative types.AdPositionsList of MapsMaps of LineTypes to an array of allowed position types.Boolean(true/false)Can be true or false depending on whether the callsucceeded or not.SuccessCampaign Management APIfor News PublishersNovember 202117
GetAllChannelsUse GetAllChannels to retrieve a list of channels that can be used in a campaign.Listed by channel UUID, along with channel Name and channel Sections.The GetAllChannels method requires only your SessionId as input.GetAllChannels Input escriptionSessionId obtained from InitSession call.GetAllChannels Example Request Payload{"method": "GetAllChannels","id": "Request-012345","params": {"SessionId": pc": "2.0"}GetAllChannels Output onArray of the channel IDs owned, listed bychannel UUID, with the channel Name andchannel Sections.Channels: channelUUID CollectionUUIDs of channels, as defined.SectionsNameSuccessCampaign Management APIfor News PublishersArray ofStringsStringChannel Section IDs per channel UUID.Channel Name per channel UUID.BooleanCan be true or false depending on(true/false) whether the call succeeded or not.November 202118
Campaign and Line Creation and ManagementMethods in this section allow you to create, modify, and delete campaigns and lines.Resource URLPOST hod NameDescriptionCreateCampaignThe method to create a campaign.CreateLineThe method to create a line.UpdateCampaignThe method to update a campaign.UpdateLineThe method to update a line.DeleteCampaignThe method to delete a campaign.DeleteLineThe method to delete a line.CreateCampaign Example Request equencyCap":"1","FrequencyCapUnit": "DAY", //v3 lia/ACT"}},"jsonrpc":"2.0"}Campaign Management APIfor News PublishersNovember 202119
CreateCampaignUse CreateCampaign to specify campaign details when creating a campaign.CreateCampaign Input dStringYesSessionId obtained from InitSession call.CampaignTypeStringYesValues: Direct HouseAdvertiserNameStringYesA free-form text input with a 255 characterlimit. No validations.ReferenceNumberStringNoA campaign-level reference you can free-formtext input with a 255 character limit. Novalidations.NumericStringYesUse GetAvailableCampaignCategories toretrieve a list of Category Ids and categoryinformation.StringYesThe name of the campaign. Must be a uniquename within the org.NoCampaign-level frequency cap per day. Thisranges from 1-20 or unlimited.CategoryIdCampaignNameFrequencyCapString If no frequency cap is passed in, the defaultis set to unlimited. The campaign-level frequency capoverrides the line-level cap for inventorypurposes if the campaign frequency cap isless than the line level frequency cap. Forexample, if the campaign frequency cap is 1/day and line frequency cap is 2/day).However, if the campaign frequency cap isless that the line frequency cap, the systemuses the line frequency cap campaign-levelfrequency cap per day. This ranges from1-20 or unlimited. If no frequency cap is passed in, the defaultis set to unlimited. The campaign-level frequency capoverrides the line-level cap for inventorypurposes.Campaign Management APIfor News PublishersNovember 202120
StringFrequencyCapUnitNoDefines the max number of ads a user can seewithin a defined timeframe.Note: FrequencyCapUnit is supported in /v3only.Values:HourDefines the max number of ads a user can seewithin an hour. For example, if theFrequencyCap of a line is set up to show onead per hour, then this line cannot serve to theuser until the next hour in a user’s local time.DayDefines the maximum number of ads a usercan see within a day in UTC. For example, ifthe FrequencyCap of a line is set up to showone ad per day and if user sees the ad at10PM UTC, then the line can serve to thesame user the next day past 12AM UTC.WeekDefine max number of ads a user can seewithin a week. For example, if theFrequencyCap of a line is set up to show onead per week, then this line cannot serve to theuser until the next 7 days.TimezoneStringNoThe default is UTC. Use the GetAvailableTimeZones method to retrieve a complete listof supported time zones.Note: If you change a campaign time zonevalue, it can result in newly created linesdefaulting to the ReserveInventory parameterset to False.Campaign Management APIfor News PublishersNovember 202121
CreateCampaign Example Request equencyCap":"1","FrequencyCapUnit": "DAY", //v3 lia/ACT"}},"jsonrpc":"2.0"}CreateCampaign Output ParametersParameterCampaignData: CampaignIdTypeNumericStringDescriptionId of the created campaign.CampaignData: StateStringState of the campaign. In the initialcreation of the campaign, the state will beNew.CampaignData: CampaignNameStringName of the campaign.SuccessCampaign Management APIfor News PublishersBooleanCan be true or false depending on(true/false) whether the call succeeded or not.November 202122
CreateLineA line controls the targeting and placement of an ad. An ad is a creative object such as abanner or a video. A line defines when, where, and to whom that ad will be shown.It is recommended to first call GetTargetingDetails to obtain the specific values neededfor some parameters used with CreateLine.CreateLine Input escriptionSessionId obtained fromInitSession call.LineDataCollectionYesLineData holds all parametersneeded for line creation.NumericStringYesThe Id of the campaign whichcontains your line. To retrieve aCampaignId, useGetCampaignSummary.Lines: LineNameStringYesThe name of the line. Must beunique within the campaign.This field has a 255 characterlimit.Lines:StringNoAvailable to use to identify theline in external systems.Lines: LineTypeStringYesSee Line Type, Creative Type,and Ad Position Values andValues per Supported IABFormat.Lines: CreativeTypeStringYes (atleast 1 perline type)Lines: CampaignIdExternalLineReferenceIdCreativeType includes IABformats must be with at least 1other banner type.See Line Type, Creative Type,and Ad Position Values andValues per Supported IABFormat.Lines: AdPositionList of StringsYes (atleast 1 perline type)AdPosition values determineexactly where the ad is shown,depending on theCreativeType.See Line
The API generally follows the functionality and workflow of Workbench. If you are new to the API, start with familiarizing yourself with Workbench functionality to gain context when utilizing the API. Authentication and Access Authentication is the first step in utilizing the Campaign Management API for News Publishers.
