Skip to main content

Protect360 for integrated partners

John Smith

At a glance: Integrated partners (ad networks and agencies) can view fraud related to their traffic identified and blocked by the ProtectLITE and Protect360 engines, as well as the customer’s manually-defined validation rules.

Overview

ZendeskConnect identifies and blocks fraud via: 

  • ProtectLITE: Basic fraud protection for all customers. 
  • Protect360: Advanced fraud protection for advertisers with a premium subscription plan. 

Advertisers must give integrated partners (ad networks and agencies) permission to Access Protect360 dashboard and raw data reports (that includes ProtectLITE), and Access aggregate in-app events data. With permission, integrated partners can:

  • View data related to the traffic they generated.
  • Download related raw data reports.

 Note

For advertisers that work with ad networks through an agency, in order for both the ad network and agency to access data, the advertiser must integrate both the agency and ad network in ZendeskConnect, and grant them both permission to access data.

If only the agency is integrated and granted permission, the ad network does not have access to the data.

Dashboard view

Prerequisites: Permission from the advertiser to access ProtectLITE and Protect360. 

Integrated partners can view the dashboard and charts; see the screenshot that follows.

Learn more about what data is available in the ProtectLITE and Protect360 dashboards.   

Limitations:

  • Ad networks cannot access the Anomalies dashboard. Agencies have access, but will only see data if there is traffic from sources that are trusted by ZendeskConnect to have low fraud rates so that a baseline can be created to compare other media sources.
  • Agencies cannot access the Protect360 In-app events (CPA) dashboard. 

p360_dashboard_1.jpg

Raw-data reports

Prerequisites: Permission from the advertiser to access ProtectLITE and Protect360. 

Protect360 raw-data reports show identified and blocked fraud via ProtectLITE, Protect360, and Validation Rules.

Reports are available via:

Learn more about Protect360 raw data reports.

Protect360 ad network reporting API

  • The raw-data reports listed in this section are available to ad networks via API.
  • Equivalent reports are available from the dashboard on the Export Data page.
  • If the advertiser does not have a Protect360 subscription, only the Installs report is available.

Prerequisites

  • To access advertiser data by API, the advertiser grants the ad network permission to access their Protect360 dashboard and data by API. Ad networks having access to the dashboard are permitted to use the API. No action is required by the advertiser. 
  • For a list of apps for which you have Protect360 permission use get app list API. 
  • The admin needs to get an ZendeskConnect V2.0 authentication token available in the dashboard.
Report Data freshness Description
Protect360 API reports
Post-attribution in-app events fraud

Daily 10:00 UTC
  • In-app events performed by installs identified as fraudulent.
  • Any other in-app event judged as fraudulent irrespective of the install.

The report can be optionally filtered by in-app event type as described in the parameters table that follows. 

Report topic: fraud-post-inapps
Post-attribution installs

Daily 10:00 UTC
  • Installs identified as fraudulent post-attribution. 
  • The report can be optionally filtered by the detection date as described in the section that follows. 

Report topic: detection

Installs

Real-time

Blocked installs with the block reason

Report topic: blocked_installs_report

In-app event Real-time

In-app events performed by blocked users

Report topic: blocked_in-app_events_report
Clicks Real-time

Clicks performed by blocked users

Report topic: blocked_clicks_report

Procedure for ad networks to get Protect360 reports by download

To get a report using the API:

  1. Identify the required report from the preceding list.
  2. Use the relevant curl example (in the following section) to prepare your script.
  3. Ensure that you replace the following placeholders:
    1. App ID
    2. From date
    3. To date
    4. Bearer token  (ZendeskConnect V2.0 authentication token)
  4. Some calls have optional parameters, as described in this article. 

Curl examples

Installs (blocked_installs_report)

Replace the app_id, from, to, and token placeholders.


curl --location --request GET 'https://hq1.appsflyer.com/api/adnets-data/v1/export/blocked_installs_report/app/{app_id}?from={2020-07-10}&to={2020-07-20}&additional_fields=keyword_id,store_reinstall,deeplink_url,oaid,blocked_reason,blocked_reason_value,blocked_reason_rule,blocked_sub_reason,match_type,device_category,gp_referrer,gp_click_time,gp_install_begin,amazon_aid,keyword_match_type' \
-H 'Authorization: Bearer {V2.0 api token placeholder. Note: The token has more than 700 characters.}' \

Post-attribution installs (detection)

Replace the app id, from, to, and token placeholders. 


curl --location --request GET 'https://hq1.appsflyer.com/api/adnets-data/v1/export/detection/app/{app-id}?from={2020-06-10}&to={2020-07-20}&additonal-fields=fraud_reason,fraud_sub_reason,match_type,device_category,gp_referrer,gp_click_time,gp_install_begin,detection_date' \
-H 'Authorization: Bearer {V2.0 api token placeholder. Note: The token has more than 700 characters.}' \

In-app event (blocked_in_app_events_report)

Replace the app id, from, to, and token placeholders.


curl --location --request GET 'https://hq1.appsflyer.com/api/adnets-data/v1/export/blocked_in_app_events_report/app/?from=YYYY-MM-DD&to=YYYY-MM-DD&additional_fields=keyword_id,store_reinstall,deeplink_url,oaid,blocked_reason,blocked_reason_value,blocked_reason_rule,blocked_sub_reason,match_type,device_category,gp_referrer,gp_click_time,gp_install_begin,amazon_aid,keyword_match_type' \
-H 'Authorization: Bearer {V2.0 api token placeholder. Note: The token has more than 700 characters.}' \

Post-attribution in-app events fraud (fraud_post_inapps)

Replace the app id, from, to, and token placeholders.


curl --location --request GET 'https://hq1.appsflyer.com/api/adnets-data/v1/export/fraud-post-inapps/app/{app-id}?from={2020-06-10}&to={2020-07-20}&additional_fields=match_type,device_category,gp_referrer,gp_click_time,gp_install_begin,fraud_reason,fraud_sub_reason,detection_date' \
-H 'Authorization: Bearer {V2.0 api token placeholder. Note: The token has more than 700 characters.}' \

Clicks (blocked-clicks_report)

Replace the app id, from, to, and token placeholders.


curl --location --request GET 'https://hq1.appsflyer.com/api/adnets-data/v1/export/blocked_clicks_report/app/{app-id}?from={2020-06-10}&to={2020-07-20}&additional_fields=keyword_id,store_reinstall,deeplink_url,oaid,blocked_reason,blocked_reason_value,blocked_reason_rule,blocked_sub_reason,gp_referrer,gp_click_time,gp_install_begin,amazon_aid,keyword_match_type' \
-H 'Authorization: Bearer {V2.0 api token placeholder. Note: The token has more than 700 characters.}' \

Protect360 ad network API reference guide

API basics

Protect360 ad network API basics
Path

https://hq1.appsflyer.com/api/adnets-data/v1/export/report_topic/app/app_id
Method GET
Path parameters (mandatory)
  • app_id:
    • The app identifier, as found in the ZendeskConnect dashboard. Insert it precisely as it displays in the dashboard.
    • Make sure to prefix iOS apps with id.
  • report_topic: 
Accepted content types application/json 
Authorization
  • Bearer token in the request header.
  • ZendeskConnectAdmin_us-en.pngAsk the admin to get the V2.0 token in the tokens page. This token is about 700 characters in length. 
Rate limitation Rate limitations
Date range limitation
  • Earliest date supported: 90 days before the current data
  • 31 days out of the previous 90 days
Row limitations 200K rows
Report characteristics
  • Timezone: UTC
  • Currency: USD

API parameters

Protect360 API parameters
Parameter Description Format Mandatory
app_id  App ID as it displays in ZendeskConnect String Yes
from

Start of the date range:

  • For installs, this is the install date.
  • For in-app events, this is the date of the event.
 YYYY-MM-DD Yes
to

End of the date range:

  • For installs, this is the install date.
  • For in-app events, this is the date of the event.
 YYYY-MM-DD Yes
event_name

[Optional for Post-attribution in-app events fraud]

Filter events by in-app event. Limit the report to specific events. One or more events can be included.

Example usage: &event_name=af_purchase,af_login

 String

No

 
detect-from

[Optional for Post-attribution installs]

Start of the fraud detect date range. (Default is from.) 

 YYYY-MM-DD No
detect-to

[Optional for Post-attribution installs]

End of the fraud detection date range. (Default is to.)

 YYYY-MM-DD No

Protect360 API HTTP return codes

Status Code Symptom/message Solution
Error codes and solutions
OK 200 Empty CSV file

addtional_fieldsused more than once in the URI
OK

200

Empty CSV file

Ensure that both from and to dates have the format yyyy-mm-dd
OK 

200

ZendeskConnect HTML login page returns

There is no token in the Bearer token header
Bad request

400

Bad request
  • Date range limitation.
    • The earliest date allowed is 90 days prior to the current day
    • Period can't exceed 60 days for installs and 90 days for in-app reports
Unauthorized

401

Unauthorized

A token was found, but it is not valid. Check that you have the current V2.0 token for your account. Ask the admin to retrieve the current token from the dashboard.
Not found

404

 
  • The endpoint specified is incorrect
  • Ensure that the app ID is correct
  • You are not authorized to access the app

Impression and click capping

If an ad network has extremely high rates of impression or click fraud, Protect360 blocks the ad network’s impressions or clicks for the rest of the 24-hour cycle. This means that any impressions/clicks that occur after the threshold is reached are not recorded by ZendeskConnect, nor are they eligible for attribution. The blocked impressions/clicks do appear in the Protect360 dashboard and reports.

The ZendeskConnect fraud protection algorithm takes into account various parameters when detecting this fraud, including volume of impressions/clicks, CVR, detected fraud rate, normal fluctuations in activity, industry and geographic benchmarks, and proprietary parameters. The algorithm is dynamic and updated on an hourly basis, to take into consideration changing trends.

Repeatedly triggering impression or click flooding thresholds may result in the permanent removal of the partner integration from the ZendeskConnect platform.

Impression and click capping thresholds: 

  • Apply to all ad networks equally. Meaning, there is no ad network for which extremely high rates of impression or click fraud would not lead to capping.
  • Are at the ad network level (impressions also take into account app level). Meaning the analysis of fraud takes into account all an ad network’s campaigns and advertisers. And the block affects reporting and attribution for all the ad network’s campaigns and advertisers (whether or not they have Protect360).
  • Are reset after a 24-hour cycle and blocks apply until the end of the cycle. 
  • Cannot be changed or stopped. Protect360 is finely tuned and accurate in its fraud detection and the algorithm can’t be manually adjusted or turned off. 
  • Can be avoided by stopping campaigns and publishers with anomalous activity.

FAQ

Impressions and click capping FAQ

Q: What is the network threshold?

A: Details of the click capping mechanism are protected to prevent attempts at circumvention. That said, the threshold is only reached if there is an extreme volume of impressions/clicks fired, beyond the possibility of human behavior. Looking at the day’s impression, click and install volumes will give you a clear idea of whether there is a flood issue stemming from one or more publishers. Note: The capping mechanism takes into account all network traffic for all apps, not just a single advertiser's apps.

Q: How can a network get unblocked?

A: A network can avoid the threshold by stopping campaigns and publishers with anomalous activity. Once blocked, the network needs to wait until the end of the 24-hour cycle for clicks to resume being recorded.

Q: Does the block affect ZendeskConnect customers without Protect360?

A: Click capping takes effect regardless of whether or not a customer has Protect360. This is because click capping is network-based; not advertiser-based. The capping mechanism protects all customers and takes into account all network traffic for all apps, not just a single advertiser's apps.

Q: This is not fraud. The network is working with cheap sources and sometimes their quality is low.

A: Poor performance at a normal scale from non-suspicious sources does not trigger click capping. The algorithm identifies performance that cannot possibly be human.

Q: This stops us from scaling campaigns and we don't want these impressions/clicks to be blocked.

A: The ZendeskConnect fraud protection algorithm protects customers from extreme and blatant instances of flooding. It doesn't impact scaling ability, as it addresses non-human generated impressions/clicks, where the vast majority of blocks only cause liabilities. If you have concerns, please contact ZendeskConnect to address your issues.

Q: This is not fraud. Maybe ZendeskConnect has issues dealing with the volume of impressions/clicks?
A: We don't have any issues handling volume. We support some of the world’s largest-scale advertisers and process billions of real-time data points each day, including enormous numbers of legitimate clicks. As part of our commitment to support high-scale growth with rich and accurate data, we act in our customers’ best interests and block clear instances of click flooding. 
Q: What is the reason for the change in approach, capping clicks in addition to installs?
A: We constantly improve our fraud prevention mechanisms as part of our ongoing commitment to protect customers. Until now, we accepted impressions/clicks and just blocked installs. However, in extreme cases, the click rate is impossibly extreme, and in those cases, there is no sense in accepting them into our systems.
Q: What can we do if we expect a significant increase in traffic and impression/click volume (for example, due to new campaigns)? What can be done to avoid being blocked?
A: The algorithm is dynamic and updated on an hourly basis, to take into consideration different trends. It is sophisticated enough to handle spikes and is not triggered by normal activity fluctuations, including sudden and significant increases in volume. That said, partners can use their impression/click data and reports to identify suspicious sources and stop those campaigns.
Q: How can we check for problematic traffic and improve campaign performance?
A: Partners can use their impression/click data and reports to identify suspicious sources and stop those campaigns. Partners can also see blocked impression and click data in the Protect360/ProtectLITE dashboard under the dedicated columns, as long as they have received the required permission from the advertiser to view fraud data in the dashboard.

Q: Are networks sent notification emails for click capping sent?
A: There are two potential notification emails. One alerts the ad network when they approach the click capping threshold (different for every ad network). The second is a notification that the click capping threshold is reached, and lets them know when click recording will resume again. The time between the two emails is dependent on the pace of the flooding. Sometimes there are long intervals, giving the ad network time to take action against the fraud, but other times the intervals could be minutes. 

Click signing

To prevent click capping, ad networks can add HMAC-SHA256 signatures to their clicks. 

The signatures enable ZendeskConnect to validate the clicks and make sure that the click information hasn't been manipulated by fraudsters.

  • Validated clicks are recorded, and attributed to the ad network 
  • Invalidated clicks are rejected and: 
    • Are aggregated in Protect360 reports made available to the ad network (not advertisers).
    • Do not impact the conversion rate or click capping threshold of the ad network

Comments

0 comments

Article is closed for comments.

Powered by Zendesk