criteo ads api

参考:

https://developers.criteo.com/marketing-solutions/docs/create-your-developer-account

https://developers.criteo.com/marketing-solutions/docs/create-your-organization

https://developers.criteo.com/marketing-solutions/docs/managing-my-organization

https://developers.criteo.com/marketing-solutions/docs/managing-my-app

https://developers.criteo.com/marketing-solutions/docs/authentication

https://developers.criteo.com/marketing-solutions/docs/analytics

https://developers.criteo.com/marketing-solutions/docs/partner-migration-guide-from-mapi-to-criteo-api

https://developers.criteo.com/marketing-solutions/docs/is-criteo-api-for-you

https://developers.criteo.com/marketing-solutions/docs/use-cases

https://developers.criteo.com/marketing-solutions/v2020.10/reference/analytics-1   :重要,接口调用说明 & 注意切换版本

https://developers.criteo.com/marketing-solutions/docs/onboarding-checklist

https://developers.criteo.com/marketing-solutions/docs/set-scope

https://developers.criteo.com/marketing-solutions/docs/send-consent-request

https://developers.criteo.com/marketing-solutions/docs/authorization-requests

https://developers.criteo.com/marketing-solutions/docs/start-using-your-api-connection

https://developers.criteo.com/marketing-solutions/docs/requesting-a-report

https://developers.criteo.com/marketing-solutions/docs/migration-guide-statistics-v1-to-v2020-10

https://developers.criteo.com/marketing-solutions/docs/get-advertiser-portfolio

https://developers.criteo.com/marketing-solutions/docs/advertisers

https://developers.criteo.com/marketing-solutions/docs/campaigns

https://developers.criteo.com/marketing-solutions/docs/frequently-asked-questions

https://developers.criteo.com/marketing-solutions/docs/developer-support 

https://developers.criteo.com/marketing-solutions/docs/how-to-handle-api-errors

https://developers.criteo.com/marketing-solutions/docs/api-troubleshooting-tips

https://developers.criteo.com/marketing-solutions/docs/api-client-libraries  :站在巨人的肩膀上  if there have

 

 

Before you start, you’ll need to get your credentials so that you can make API requests. Your credentials are made up of an API Key and API Secret.

These allow you to access the API without needing to provide a username and password each time you make a call. Your credentials also determine which permissible actions that your app can perform.

To get your credentials:

  1. Log in to the Criteo Developer Dashboard and go to your app page (My Apps and click on view to select an app)
  2. Click on Generate and download new key to generate your set of credentials
  3. A text file will be automatically downloaded with both your API Key and API Secret. You can copy your key from the credentials dashboard as often as you need, but we can only share the secret with you once. Please save it somewhere safe!
  4. You can then authenticate using the key and the secret using the /oauth2/token endpoint to get your token
https://api.criteo.com/oauth2/token

You can use this dashboard to manage your API keys. You can also delete an API key from this dashboard. The key will stay valid for fifteen minutes before deactivating.

💡 You can change the name of your set of credentials by clicking directly on the credentials name in the dashboard. For example, Troubleshooting Credentials or Production Credentials.
💡 You will be limited to five API credentials for an app (for ex. one for production, one for troubleshooting, and three others for any other use cases you'd like)

 

Managing My Organization

 

This article will explain how to edit your organization's information.

  1. From the navigation, select Settings
  1. Click the pencil logo to edit your current organization information and save your changes
  1. If you want to change another organization's information
    a. Go back to the My Apps screen
    b. Select the Organization in the Organization screen accessible at the top right corner

c. Change the Organization

d. Follow steps 1 and 2

If you have any question about the required fields, see the Create your organization guide.

 

Authentication

 
  • To get started with our APIs, use the endpoint below to generate an Access Token with your API credentials
  • The Access Token is a Bearer token to be included in the Authorization Header of all API requests
  • Multiple tokens may be generated and each are valid for 15 minutes, or 900 seconds
 
 
Endpoint
  • POST https://api.criteo.com/oauth2/token Generate an Access Token

📘

Generate another access token when it expires, signaled by a 401 Unauthorized HTTP status code

 
 
Parameters
ParameterDescription
client_id string Please see below for instructions on getting your credentials through Developer Dashboard
client_secret string Please see below for instructions on getting your credentials through Developer Dashboard
grant_type string Must be client_credentials
 
 
Generate an Access Token
  • This endpoint generates a new access token using your API credentials
  • To comply with the OAuth2 standards of using client_credentials, Criteo API authorization now supports Content-Type: 'application/x-www-form-urlencoded'. See the example below.
POST https://api.criteo.com/oauth2/token
// Sample Request curl --location --request POST 'https://api.criteo.com/oauth2/token' --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'client_id=CLIENT_ID' --data-urlencode 'client_secret=CLIENT_SECRET' --data-urlencode 'grant_type=client_credentials' // Sample Response { "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IkVuTTBCZkFELUFrNXZwOU9RMW1ZWXR6T2RaMUVad2RWaHY5T3Z2cVA3YVUiLCJ0eXAiOiJKV1QifQ.eyJjdHg6dXNlcjpkaXNwbGF5TmFtZSI6IkJvYmJ5IFNpYW8gTGVpIEhhbiIsImN0eDp1c2VyOmVtYWlsIjoiYi5oYW5AY3JpdGVvLmNvbSIsImN0eDp1c2VyOnVpZCI6ImIuaGFuIiwiY3R4OnVzZXI6dW1zSWQiOiIzMjM4ODQiLCJzdWIiOiJ1Omk6Yi5oYW5AY3JpdGVvLmNvbSIsImlhdCI6MTYwMTQwNDM1NSwiZXhwIjoxNjAxNDA1MzE1LCJhZGQ6bWFwaTp1bmFtZSI6ImIuaGFuIiwic2NvcGUiOiJnYXRld2F5IiwiY2xpZW50X2lkIjoiYi5oYW4iLCJuYmYiOjE2MDE0MDQ0MTUsImlzcyI6ImNyaXRlby1leGFtb2F1dGgifQ.OI1W8utCbR2a2VbkxOZZaP2JyQ4b8Kf9R2x_yGRp9jjqclvm8huC_iHb9AECLmYVMUYWojvmbIOk0j0BRfLf1xYoOAIvNbcWN-SsrkYOXVh9mYruwOfKJb0t6j8MW7u03PbfvSRtn_29ar3V-7rimDqdMR_iTVhTlBLI0W3jSOCjzKK9sbg0REwtneBu4V3dFLaLNIxXj5EtyaTpLB3v71smFljBHtUC1Go8wRUX2P_GZfWYJCZhatx0xsN46oS8aGQl3a6N4nh4cqdJNA83Y44LYEKpky0ZmBwC9D5j9rpC-BDkUaeWlgkVSicy6yWh-S06JC4e3pJwUHskUMvoiA", "token_type": "Bearer", "expires_in": 900 }

🚧

Mandatory Content-Type header

Please ensure you include Content-Type: application/x-www-form-urlencoded header in your call to /oauth2/token endpoint.

 
 
Use an Access Token
  • Once you have obtained your access token, you can authenticate all subsequent requests by including an Authorization HTTP header, as in the example below:
GET https://api.criteo.com/2020-10/advertisers/me Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IkVuTTBCZkFELUFrNXZwOU9RMW1ZWXR6T2RaMUVad2RWaHY5T3Z2cVA3YVUiLCJ0eXAiOiJKV1QifQ.eyJjdHg6dXNlcjpkaXNwbGF5TmFtZSI6IkJvYmJ5IFNpYW8gTGVpIEhhbiIsImN0eDp1c2VyOmVtYWlsIjoiYi5oYW5AY3JpdGVvLmNvbSIsImN0eDp1c2VyOnVpZCI6ImIuaGFuIiwiY3R4OnVzZXI6dW1zSWQiOiIzMjM4ODQiLCJzdWIiOiJ1Omk6Yi5oYW5AY3JpdGVvLmNvbSIsImlhdCI6MTYwMTQwNDM1NSwiZXhwIjoxNjAxNDA1MzE1LCJhZGQ6bWFwaTp1bmFtZSI6ImIuaGFuIiwic2NvcGUiOiJnYXRld2F5IiwiY2xpZW50X2lkIjoiYi5oYW4iLCJuYmYiOjE2MDE0MDQ0MTUsImlzcyI6ImNyaXRlby1leGFtb2F1dGgifQ.OI1W8utCbR2a2VbkxOZZaP2JyQ4b8Kf9R2x_yGRp9jjqclvm8huC_iHb9AECLmYVMUYWojvmbIOk0j0BRfLf1xYoOAIvNbcWN-SsrkYOXVh9mYruwOfKJb0t6j8MW7u03PbfvSRtn_29ar3V-7rimDqdMR_iTVhTlBLI0W3jSOCjzKK9sbg0REwtneBu4V3dFLaLNIxXj5EtyaTpLB3v71smFljBHtUC1Go8wRUX2P_GZfWYJCZhatx0xsN46oS8aGQl3a6N4nh4cqdJNA83Y44LYEKpky0ZmBwC9D5j9rpC-BDkUaeWlgkVSicy6yWh-S06JC4e3pJwUHskUMvoiA Accept: text/plain Content-Type: application/*+json
 
 
Get your credentials through the Developer Portal (self-service)
  • To get your credentials, you need to create a Criteo account and then create an Organization and an App within the Developer Dashboard
  • Learn how to create an Organization and an App in these related articles Create your organization and Create your app
  • Once you have created an App you will be able to generate a set of Credentials through the following dashboard:
  • 💡 When creating a set of Credentials, you will automatically download a file with your API Key and API Secret like this
  • Make sure to keep your API Secret saved somewhere secure. We can only share the API Secret once with you!
  • You can use this dashboard to manage your API keys. You can also delete an API key from this dashboard. The key will stay valid for fifteen minutes before deactivating
  • 💡 You can change the name of your set of credentials by clicking directly on the credentials name in the dashboard. For example, Troubleshooting Credentials or Production Credentials
  • 💡 You will be limited to five API credentials for an App (for ex. one for production, one for troubleshooting, and three others for any other use cases you'd like)
 

Analytics

 

 

 
 
Statistics API Endpoint
https://api.criteo.com/2021-04/statistics/report
 
 
Introduction

The Statistics API endpoint allows you to retrieve data related to your campaigns' performance. The specific metrics returned and the dimensions that the data is grouped by can be customized.

This enables you to merge Criteo data with other sources, build business alerting on Criteo data or programmatically manage ad spend based on campaign performance. 

This provides granularity and flexible insights to help you optimize your campaigns and better understand the results they are delivering. 

 

🚧

Stats v2021-04 and v2020

An older version of the Statistics API remains available at this API endpoint:

https://api.criteo.com/marketing/v1/statistics

Documentation for this legacy version remains available in the v2020 documentation:

https://developers.criteo.com/marketing-solutions/v2020/docs/statistics-v1

 

 
 
New Features in Stats Since v2021-01

Since v2021-01, Criteo's Statistics API introduces several new metrics that relate to different marketing goals and channels, including app, web and store campaigns.

Additionally, you can now specify your time zone, keep track of your product category history and retrieve a nearly real-time look at your data and campaign performance.

🚧

Known Limitation in v2021-01+

  • The maximum number of returned rows per request is limited to 100,000. As a result, you may need to fetch highly granular data by making several smaller requests.

This limitation will be addressed in future releases of the /statistics/report endpoint.

 

/oauth2/token

curl --request POST \ --url https://api.criteo.com/oauth2/token \ --header 'Accept: text/plain' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data grant_type=client_credentials \ --data client_id=c5d5************249 \ --data 'client_secret=DxCwd8***********ETaxoX0N'

 

var client = new RestClient("https://api.criteo.com/oauth2/token");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "text/plain");
request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
request.AddParameter("application/x-www-form-urlencoded", "grant_type=client_credentials&client_id=c5*******9&client_secret=D********N", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

  

{

"access_token":
"e************..."
"token_type":
"Bearer"
"expires_in":
900

}

 

 

 

Requesting a Report

 
 
 
Retrieving Statistics for a Specific Advertiser

The Statistics API allows measurement and reporting on campaigns using the metrics and dimensions you specify.

https://api.criteo.com/2021-04/statistics/report
{ "advertiserIds": "12345", "startDate": "2020-09-10T04:00:00.000Z", "endDate": "2020-09-14T04:00:00.000Z", "format": "csv", "dimensions": ["AdsetId","Day"], "metrics": ["Displays","Clicks"], "timezone": "PST", "currency": "USD" }

 

A report is generated via a POST call and the results are returned directly in the response.

AdsetId,Day,Currency,Displays,Clicks 54321,2020/9/10,USD,2534,35 54321,2020/9/11,USD,6234,96 54321,2020/9/12,USD,4357,54 54321,2020/9/13,USD,3245,45 54321,2020/9/14,USD,4584,72

 

 
 
Response Codes

The following response codes may be returned by the API:

400: Bad request, invalid syntax or validation error. Review the request to make sure the format is valid.
401: Authentication failed. Ensure the authentication header is formatted properly and your access token hasn't expired.
403: No campaign found. Verify your campaign IDs are correct.
429: Throttling failure. Wait a minute to try again - there is a limit of 200 requests per minute.
500: Unknown error.

 

 

Partner Migration Guide from MAPI to Criteo API

 
 
 
Overview

On June 15th, 2021, our Marketing API (MAPI) will be deprecated. All MAPI users should finalize migration prior to this date. On December 9th, Criteo launched a new API for sending audiences and retrieving campaign statistics, the Criteo API. Criteo API was released into GA in January 2021.

For partners, this migration requires several changes to how you interact with our APIs. This guide is intended to help provide clear instructions for partners about how to migrate from MAPI to the new Criteo API.

 
 
Migration Path

This guide is to provide instructions for partners who are currently using the Marketing API and who would like to migrate to the new Criteo API. If your organization is integrated using our legacy API, the Partner API (PAPI), please consult this documentation.

 
 
Key Differences

Below are the three primary differences for partners currently using MAPI to consider when adopting the Criteo API:

  • App-based API credentials: MAPI requires partners to utilize client credentials for each advertiser on behalf of whom they make requests. The Criteo API allows a more partner-centric credential approach. Partners may create a single set of credentials for each App they create in the Developers Dashboard across all Criteo clients for whom they make requests. Learn more here about permissions and authorization requests

  • Authentication: The Criteo API upgrades our APIs to the standardized OAuth2 authentication flow. This includes some changes to URL-form Encoded content-type that require an update to the headers used during authentication

  • Endpoints: MAPI endpoints will be deprecated on June 15th, 2021. Partners must migrate to the new Criteo API endpoints to send audience identifiers (see our Audiences API Guide), retrieve statistics (see our Analytics API Guide ), or perform other types of requests in order to continue interacting with Criteo’s platform on behalf of mutual clients.

  • A more detailed migration guide can be found here.

 
 
Sample Migration Plan

Below is a migration plan to provide a recommended implementation approach for migrating from MAPI to the new Criteo API.

 
 
Phase 1: Set Up

Sign up on the Developers Portal. Create an app. Request client permission for access to the required advertiser identifiers and within the functional scope of your organization’s App (e.g. Analytics, Audience, etc. . . .). Please consult the Onboarding Checklist for a more detailed step-by-step and Criteo API introduction.

 
 
Phase 2: Implementation

Create a new authentication flow to conform to the Criteo API’s new OAUTH2 authentication requirements. Modify the endpoints to reflect the new Criteo API’s endpoint specification.

 
 
Phase 3: Testing

Perform internal UA testing on the new version of your Criteo connector. Send test data to Criteo’s test advertiser identifier to perform a final validation of the connector API migration.

 
 
Phase 4: Migration & Release

Disconnect your legacy partner MAPI connector and enable the new Criteo API partner connector to allow sync between your platform and the Criteo API across all live mutual clients for whom you send Criteo API requests.

🚧

Timing

Be sure to time this migration in a manner so that any existing audience syncs made on behalf of mutual clients are not interrupted (e.g. any triggers from the partner platform that are intended to update Criteo audiences should be pointed at the new connector prior to disabling the legacy MAPI connector to ensure that no updates are lost during the migration process).

The migration workflow is only a suggested approach. This code update can be managed in the way that suits the needs of your engineering team. The actual migration will take only a few hours, in total, of engineering dev resources. However, some partners may find it useful to spread this work out over the course of several days.

 
 
Additional Resources
  • Test our requests on the Criteo API within an interactive UI format using our Criteo API Swagger Tool

  • Keep up to date with any changes or new features by consulting the Changelog

  • Connect with other to chat about questions or wins in Criteo’s Developer Community Discussion Forum

 
 
Additional Support

Please feel free to reach out to partnerships-support@criteo.com if you have any additional issues or questions!

 

 

Consent URL Generation

 
 
 
Introduction

The Criteo API allows you to build custom apps that help the world's advertisers grow their businesses.

In order for your app to function, your users will have to delegate permissions for one or more of the Criteo advertisers that they oversee.

To do this, you will need to direct the user to a unique consent delegation page. The URLs for this type of page can be generated in one of two ways - manually from your Criteo App page, or programmatically using a cryptographic key.

Both methods are described below.

These guides assume you have created a developer account, are part of an organization and have created an app. Instructions for getting started can be found here.

 

Generate Consent URLs from your Criteo App Page

Once you have logged in to the Criteo Partners Portal, navigate to your App page by clicking your app's card in the My apps section.

 

At the top of your App page, provided you have activated your app, you will see a Generate new URL button.

 

Clicking this button will generate a single consent URL which can be easily copied to your clipboard.

The URL will have two query parameters as shown below:

https://consent.criteo.com/request?nonce=<nonce>&hmac=<signature>

Each click of the button will generate a new URL. You should provide a unique URL to each user.

 

Generate Consent URLs Programmatically

In order to generate consent URLs on the fly, you will need a public and private keypair for signing your URLs.

To obtain this keypair, you will need to register a callback URL to receive confirmations. The callback process is described in full in a later section.

Once you have logged in to the Criteo Partners Portal, navigate to your App page by clicking your app's card in the My apps section.

 

Scroll down to the Connector Parameters section and click Create a new connector. You will be prompted to enter a callback URL. Once registered, your callback URL can be modified at any time and the keypair associated will remain the same.

 

Once complete, your browser will download a .txt file with your public and private keypair.

🚧

Signing Keypair Generation

The private signing key is only shared once at the time you register a callback URL. Keep it somewhere safe. If you lose your private key, you can delete and re-register your callback URL to obtain a new one.

 

Once you have your signing keypair, you will be able to programmatically generate a consent URL.

Doing so requires that you use a HMAC-SHA512 hashing algorithm to generate a signature.

The consent URL will have the following structure and parameters:

https://consent.criteo.com/request?key=<public signing key>&timestamp=<UNIX timestamp in seconds>&state=<state>&redirect-uri=<redirect URI>&signature=<hashed signature>
ParameterDescription
key Your public signing key
timestamp The UNIX timestamp of when your URL was generated, in seconds
state An arbitrary string to be included in the consent callback. For example, the User ID of your app user.
redirect-uri The URL to redirect the user to after consent delegation
signature The HMAC-SHA512 hashed query string of the previous four parameters, in order

 

The final parameter, the signature, should be the HMAC-SHA512 hashed value of the following string, using the same keytimestampstate and redirect-uri values as your URL:

?key=<public signing key>&timestamp=<UNIX timestamp in seconds>&state=<state>&redirect-uri=<redirect URI>

 

Code examples for generating a Consent URL can be found below:

using System; using System.Text; using System.Security.Cryptography; /* Enter your public signing key and signing secret in between the quotations below. You can also choose to modify your redirect URL (where your consent giver will be redirected too after they accept your consent request). You can also choose to pass in parameters inside the state object. */ public class Program { public static void Main() { // MODIFY THIS var publicSigningKey = "<public signing key>"; var signingSecret = "<private signing key>"; var redirectUri = "https://developers.criteo.com/"; var state = "userID"; // long timestamp = ((DateTimeOffset)DateTime.Now).ToUnixTimeSeconds(); var signature = createSignature(publicSigningKey, timestamp, state, redirectUri, signingSecret); Console.WriteLine(generateUrl(publicSigningKey, timestamp, state, redirectUri, signature)); } public static string createSignature(string publicSigningKey, long timestamp, string state, string redirectUri, string signingSecret) { var message = $"?key={publicSigningKey}&timestamp={timestamp}&state={state}&redirect-uri={redirectUri}"; return HmacUtil.Sign(message, Encoding.UTF8.GetBytes(signingSecret)); } public static string generateUrl(string publicSigningKey, long timestamp, string state, string redirectUri, string signature) { return $"https://consent.criteo.com/request?key={publicSigningKey}&timestamp={timestamp}&state={state}&redirect-uri={redirectUri}&signature={signature}"; } } public static class HmacUtil { public static string Sign(string message, byte[] signingKeyBytes) { using (var hmac = new HMACSHA512(signingKeyBytes)) { var hashedMessage = hmac.ComputeHash(Encoding.UTF8.GetBytes(message)); var stringBuilder = new StringBuilder(); foreach (var value in hashedMessage) { stringBuilder.Append(value.ToString("x2")); } return stringBuilder.ToString(); } } }

 

Consent Delegation Callback

Once the user has completed the Consent Delegation flow, an HTTP callback will be sent to the URL associated with the signing keypair you used.

The POST body will include a Type field, which will indicate either a successful ( value of ConsentGranted) or unsuccessful (value of ConsentDenied) consent request.

For a ConsentDenied callback, AcceptedScopes will be an empty array.

🚧

Callback Body Update

CriteoService values have been updated to improve consistency. Possible values are MarketingSolutions and RetailMedia

{ "Type": "ConsentGranted", "Data": { "Key": "971062d8161ba4ef8f78f3201a6f361f", "Timestamp": 1614366053, "State": "", "ApplicationId": 2, "ApplicationName": "Test App", "RequestedScopes": [ { "AccessLevel": "Read", "Domain": "Analytics", "CriteoService": "MarketingSolutions" } ], "AcceptedScopes": [ { "AccessLevel": "Read", "Domain": "Analytics", "CriteoService": "MarketingSolutions" } ], "Advertisers": [ { "Id": "12345", "Name": "Example Advertiser" } ] } }

Other fields include the public KeyTimestamp, and State values provided in the original consent URL.

Please note that for MarketingSolutions apps, the entities that have been shared will be in the "Advertisers" field of the callback body, but for RetailMedia apps, those entities will be in an "Accounts" field.

The callback request will also include an HTTP header named x-criteo-hmac-sha512 . Its value will be the HMAC-SHA512 hash of the callback request body, using the same signing secret value as your app.

In this way, you can use your app's signing secret to validate the integrity and authenticity of the callback.

🚧

Callbacks Only for Programmatically Generated URLs

Callbacks will only be sent for dynamically generated consent URLs. You will not receive a POST to your callback URL when user consent is provided using a link generated directly from Developer Dashboard.

 

 
 
User Redirection

Once the user has completed the Consent Delegation flow, the POST request to the callback URL and the user's redirection to the redirect URI are executed in sequence. The user will not be redirected until the callback attempt has resolved.

If the call to the callback URL fails on its first attempt, the POST will be retried up to two more times before the user is redirected to the redirect URL.

Following three failed attempts, the user will be redirected to the redirect URL and Criteo will log the callback error.

 

Is Criteo API for you?

 

With the Criteo API, you can programmatically create, manage, and scale campaigns. You may benefit from the Criteo API if you fall into one of the following categories:

  • Advertiser: You require a custom solution to programmatically create, manage, and report on your Criteo campaigns beyond what’s available in Management Center. You have internal engineering resources to connect to the API

  • Agency: You offer complementary tools to advertisers who lack the resources and bandwidth to directly integrate with the Criteo API

  • Partners: You offer complementary tools to advertisers or agencies to enrich their Criteo campaigns

Before getting started with the Criteo API, read about our API policies and the Onboarding checklist. You’ll want to have internal engineering resources to integrate and stay up to date with new versions. Each version is stable for a year, but new versions are released quarterly.

 

Onboarding Checklist

 

This checklist will take you through the process to get started with the Criteo API. The steps are divided into several categories, some of which you might decide to skip if they aren't applicable to your needs. To get the most from this document, read and execute steps in order.

The list contains three types of items:

  • ✔ To-do: Steps that are required in order to perform a certain task or set up a certain part of your app
  • 💡 Info: Information that is not critical for the process, but will help you understand the context or clarify certain steps.
  • 🚨Warning: Things to be aware of throughout the process, as they might involve additional implementation effort or incur certain risks
 
 
Getting familiar with Criteo API and products
  • ✔ Learn more about Criteo API use cases: If you already know Criteo, read our Is the Criteo API for you? article. Get some inspiration from our use cases if you are not sure to use the Criteo API
  • 💡 Learn more about Criteo: If you are new to Criteo, read our Criteo Marketing Solutions for API users (if you are an Advertiser or an Agency) or our Criteo Publishers for API users [Coming soon] (if you are an inventory provider) to learn more about Criteo API capabilities
 
 
Getting started with access

Create a Criteo developer account

  • ✔ Start by creating your Criteo account (if you already have an account please skip this step): Go to our landing page at developers.criteo.com and click on Get Started
  • ✔ Complete our registration form to create a Criteo developer account: You will receive a confirmation email to finish the process

Create your organization once you have created your developer Criteo account

  • ✔ Complete the organization details form
  • ✔ Once created you will have access to the developer portal

Modifying an Account or Organization

 
 
Learning how to use Criteo endpoints

Create an app

  • ✔ Once you have created your organization, you will have access to the MyApps page. This page will give you a summary of the apps you have created
  • ✔ To start creating an app, click on the Start building button. Define an app name, description, and image to create your app
  • ✔ These fields will be editable before publishing an app (for more details see the Managing my app section)

App name, image, and description

  • 💡 These elements will be visible to the Advertisers, Brands, or Publishers you share your app with. Make sure to provide some content describing your business and inspiring confidence to your app users

Get your app credentials

  • ✔ Get your API credentials once your app is created. Start by creating a set of credentials by clicking on generate and download a new key. This will create a new set of credentials (API Key and API Secret)
  • ✔ The API Key will be available in the credentials table and the API Secret will only be provided once (a file with the secret will automatically download when creating a set of credentials), please save it somewhere carefully! For more details about credentials, see the Create your app section

Managing my credentials

  • 💡 You will be limited to five API credentials for an app (for ex. one for production, one for troubleshooting, and three others for any other use cases you can imagine)
  • 💡 For more details about how to edit and delete credentials, see the Create your app

The API Secret shared only once

  • 🚨 The API Secret will be available in the file automatically downloaded when creating a set of credentials. Please keep it safe as it will be the only time we will be able to share it with you!
 
 
Define your app scope

Select the services you would like to access through your app (Marketing Solutions, Retail Media, or Publisher)

  • ✔ Once you have chosen a Service, click save. This action cannot be undone

Saving the Service cannot be undone

  • 🚨 Once you click on save, you won't be able to switch between Marketing Solutions, Retail Media, or Publishers any longer. So please choose carefully (In case you made a mistake, don't worry! You can just create a new app 😉)

Then select the authorizations you would need for your app

  • ✔ Click on the Save button to save your authorization selection
  • ✔ You can update the authorizations as many times as you want before validating your app through the Generate consent link button
Validate your app and generate a consent URL

Click on Generate & Copy URL to finish your app

  • ✔ This will generate a consent link you can share with an advertiser/brand/publisher to obtain authorization to access their assets
  • ✔ Changing the name, description, image, or app scope will no longer be available after the first URL creation
  • ✔ You can generate as many URLs as you want and each URL can only be used once

Validating an app sets the app information and scope

  • 🚨 Changing the name, description, image, or app scope will no longer be available after the first URL creation

More information about how authorization works

 
 
Start using your API connection

Once you click Generate & Copy URL, the consent URL will be directly copied into your clipboard

  • ✔ Share your URL by email, Slack, or any other means to your advertiser, brand, or publisher.
  • ✔ Once they click the link, they will be redirected to the Criteo Consent Portal where they can provide you with the requested authorization levels for the accounts in their portfolio

Start using the Criteo API endpoints

  • ✔ Call the portfolio endpoint with your credentials to confirm you have now access to the accounts.
  • ✔ You will then be able to use the domains in your scope for those advertisers/brands/publishers and start using Criteo APIs! 🎉

 

 

Set Up Your API Connection to Answer your Business' Needs

 

Next, you’ll want to define the scope of your API and define which domains your app needs to access. This ensures your app can connect to the right endpoints. The process is split into two steps.

  1. First, choose the Criteo product that you’d like to build with: Criteo Marketing Solutions (Management Center) or Criteo Retail Media. Click Save to access the Authorization section.

🚨 Once you save, you won't be able to switch between Marketing Solutions or Retail Media again! Make sure to choose carefully (In case you make a mistake, don't worry! Just create a new app 😉)

  1. From there, you can select which Authorizations you'll need to access. Specify whether you need “read-only” or “manage” access to your end-users’ accounts. For example, you may want “read-only” to retrieve campaign details, or you might want “manage” permissions so you can set CPCs for campaigns.

💡 You can update the Authorizations as many times as you want before validating your app through the Generate consent link button.

You will find here a list of available Authorizations in the Developer Dashboard:

Criteo Marketing Solutions:

Available

  • Reporting: Generate custom reports. Slice and dice your data across marketing goals and channels, including App, Web, and Store campaigns  
  • Targeting: Select domains/apps or publisher content that you want to include or exclude for displaying ads
  • Catalog: Retrieve your product catalog, add and edit your product details. Get status reports on your recent imports

Coming soon

  • Campaign: Set CPCs by campaign or campaign category, retrieve campaign details, and export reports 
  • Budgets: Retrieve information on the budget type, active budget status, and the status of related campaigns
  • Categories: Retrieve information for an entire account portfolio and/or across different geographic locations
  • Audiences: Create, update, or delete your Contact Lists using your own CRM segments or your lists from a third-party.
  • Creative: Use a third-party creative that is displayed by an external creative provider at display time (while still using Criteo Engine for media buying and product recommendation)
  • Reco: Call the Criteo Reco on your own website, leveraging our Shopper Graph and Product Graph

 

 

Send an Authorization Request to Your Users

 

Once you have decided your app's scope, it is time publish it!

Click on Generate & Copy URL to finish your app

  • This will generate a consent link you can share with an advertiser/brand/publisher to get authorization to access their assets
  • Changing the name, description, image, or app scope will no longer be available after the first URL creation
  • You can generate as many URLs as you want. Each URL can only be used once

🚨 Validating an app sets the app information and scope Changing the name, description, image, or app scope will no longer be available after the first URL creation.

Once you click on Generate & Copy URL, the consent URL will be directly copied into your clipboard

  • Share your URL by email, Slack, or any other means to your advertiser, brand, or publisher
  • Once they click the link, they will be redirected to the Criteo Consent Portal where they can grant the requested authorization levels for the accounts in their portfolio

 

 

Authorization Requests

 

Before an advertiser can start using an app or integration built with the API, the advertiser has to grant it access. This is accomplished through an authorization request.

All apps must send an authorization request to advertisers in order to read or manage actions on the advertiser’s behalf.

 
 
Steps
  • On the Developer Dashboard, the app developer sets up the app, picking a name, description, and logo
    • The app developer selects which permissions the app will need access to
    • The app developer generates a URL to share with an advertiser. Note: Once this URL is generated, the app name, description and scope cannot be changed
    • The app developer shares the link with the advertiser
    • The advertiser is directed to the Consent Dashboard and prompts the advertiser to login if required
    • The advertiser sees the authorization request, which has information about the app and the requested permissions
    • The advertiser decides which portfolios to grant or deny access to
    • The app is now able to send calls leveraging that advertiser’s account
 
 
Types of permissions

Each app will request different permissions, based on its purpose. These permissions will be tied to different aspects of campaigns, such as Audiences, Budgets, Creatives, or Analytics.

There are two types of permissions that an app might request.

Read-only: These permissions request access to read an advertiser’s data or campaign details. They can only pull information; they do not modify a campaign in any way. An example would be an app that reads an advertiser’s data to create campaign reports.

Manage: These permissions allow an app to make changes to an advertisers’ campaign, ad set, or ad. An example would be an app to automate setting CPCs for campaigns or uploading a Contact List.

 
 
Granting access

When an advertiser receives an authorization request, they will be redirected to the Consent Dashboard.

Here they will see information about the app, including its name, description, logo, and the app’s company name and email.

This request will include details about the requested permissions. The advertiser can choose which of its portfolios to grant access to.

 
 
Managing and revoking access

The consent dashboard is also where the advertiser can see all the apps that have been granted access.

They can see which portfolios each app has access to, the specific permissions, and when access was granted.

This is also where access can be revoked for any particular app.

 

Is the issue that my data is late?

Starting from How to handle API errors - Part 1 to now, we have focused on common issues that can arise with the API.

Let's talk about data and metrics. Data latency can also be mistaken for causing issues. Some metrics may have several hours of latency, while others may seem to have longer delays. The following table provides the maximum and median data delays for different metric groups.

Metric groupMaximum delay*Median delay*
Revenue and basic metrics, including:

- Displays, clicks, advertiser cost
Revenue metrics
- Revenue-based ROI: ECoS and related metrics
- Sales and derivative metrics:

- Sales data
- Conversion data
- Conversion-based ROI: CPO, CPI, and related metrics
12 hours 5 hours
Audience metrics:

Potential users
Exposed users
Displays
19 hours 7 hours
Omnichannel metrics 207 hours 197 hours

Retention for sales data is 4 years unless requested by hourly dimension. The hourly dimension data has 3 months of retention.

posted @ 2021-05-21 11:23  PanPan003  阅读(140)  评论(0编辑  收藏  举报