Validation rules for app owners

At a glance: Rules for target-validation and custom fraud detection (Protect360) enable app owners to ensure that installs are attributed to the most recent valid media source.  If there is no valid media source, the install is attributed to organic. 

Campaign target-validation rules control campaign results. Installs that don't meet campaign targets—are invalid—and attributed as organic installs. 

Protect360 custom fraud rules improve the ability to detect fraud. Protect360 is used to block fraudulent install attributions and correct the attribution of hijacked installs. 

Campaign target-validation rules

  • Targeting attribution validation rules enable advertisers to control which installs are attributed.
  • The rules apply to installs. They don't apply to retargeting campaigns (re-engagements and re-attributions) 
  • Installs that don't comply with the rules are attributed to organic.
  • Rules are:
    • based on: campaign name, app user geo, device type, device OS.
    • applied to installs form all sources, including agency, generated traffic.
  • Agencies can neither view nor define rules. 
  • Using rules can result in discrepancies between AppsFlyer and SRNs like Facebook Ads and Google Adwords as they deploy their own logic to validate installs.

Mechanism 

The attribution validation mechanism uses rulesets. Rulesets are configured so that they apply to defined media sources and campaigns, meaning you can have different rules for different media sources/campaigns.

Rules in the validation set are used to validate the install. Rules are based on campaign name, geo, device type, and OS version. Non-complaint installs are attributed to organic installs. 

Rulesets for agency-generated traffic

  • Rulesets for agencies depend on the relationship you have with the agency as follows:
    • Non-transparent relationship: can't be limited to specific media sources and campaigns.
    • Transparent relationship: rulesets can apply to specific media sources and campaigns, including SRNs. The rulesets of transparent agencies are similar to that of traffic you bring directly without an agency. 

The ruleset mechanism has two phases and operates as follows:

  • Phase 1: Identify the applicable ruleset
  • Phase 2: Examine the install for compliance

Phase 1: Identify an applicable ruleset

  • This phase is not applicable to non-transparent agency traffic.
  • If multiple rulesets exist, then the ruleset having the greatest granularity (most specific) by media source and campaign is used. The example following illustrates this.

 Example: Ruleset granularity 

An app owner defines four rulesets applying to different media sources and campaigns as follows.

Campaign target-validation rulesets
Ruleset Media source Campaign
1 Network_A 1
2 Network_A All
3 Network_B 2
4 All All

Ruleset 4 is the least granular. Rulesets 1 and 3 are the most granular.

App users A, B, and C, installed the app having engaged with a user acquisition campaign. The validation rules mechanism finds the most granular ruleset. 

Users who installed the app
User Media source Campaign Applicable ruleset and reason selected
A Network_D 3 4: the only applicable ruleset
B Network_A 1 1: the most granular relative to 2 and 4, which are also applicable. 
C Network_A 2 2: is more granular than ruleset 4, which is also applicable.

 

Phase 2: Examine install compliance

By using the applicable ruleset, the install is examined for rule compliance Rulesets consist of one or more rule types as follows: 

Rule types
Rule type Operators allowed Values allowed Use case example
Campaign Name*
  • Begins with
  • Ends with
  • Includes
Free text Includes campaign names with specific names
Device Type Not contains
  • Free text
  • Use the device type name exactly as it appears in the raw data reports. List of examples: iOSAndroid 
  • The field can contain multiple device types
Exclude unwanted device types
OS Version
  • Between
  • Including and above
  • Including and below 
Select using the menu Ensure that the OS version is in an approved range
Geo (Country and city) Match (list of countries/cities) 
  • Select using the menu
  • Multiple values can be chosen
Ensure that the app user is located in a specific geo
* Not applicable to non-transparent agencies

 Example: Compliance with the rules 

The screenshot that follows contains a ruleset having four rules 1-4. Each rule has a rule type, operator, and value. Note: The device type operator differs from that of the other operator types and that it uses the not contains operator. 

ValidationRule-us-en.jpgInstalls were examined for compliance. The table contains the user data and the valid/invalid outcome. The validation rules engine tests each install for rule compliance. Non-compliant installs, meaning invalid installs, are attributed to Organic. 

User installs 
User Device 
type
OS Version  Country  Campaign name Valid/invalid 
(invalid reason)
A Apple 11 China A100 Valid
B Apple 9 China B100 Invalid (OS version)
C Apple 11 Canada C100 Invalid (Geo)
D ABCD 11 China D100 Invalid (Device type=ABCD)
E ABCDEF 11 United States A100 Valid
F ABCDEF 11 United States B190 Invalid (Campaign name)

Set up target-validation rulesets

This section contains the procedures to set up validation rulesets.

Media sources and campaign considerations

Before setting up rulesets, take into consideration the following when setting media sources and campaigns:

  • Separate rulesets are used for ad networks and agencies
  • Only active media sources and campaigns display. Active means that there was at least one impression, click, or install during the past month associated with the media source/campaign.
  • Where Media source=All the ruleset applies to the current active media source campaigns and future campaigns. 
  • Where Campaign=All the ruleset applies to both existing and future campaigns.
  • Where multiple media sources are selected, AppsFlyer sets Campaign=All.
  • AppsFlyer enforces ruleset granularity logic. This means you are not able to define rulesets that disregard the logic.

To setup target-validation rulesets:

  1. Go to Configuration > Validation Rules.
    The Validation Rules window opens.
  2. Click Add Ruleset.
  3. Enter Ruleset name: Use a name that describes the ruleset, as it appears in blocked installs reports—for example, Facebook USA June.
  4. Select one of the following Ruleset types:

    Ruleset_us-en.jpg

    • Targeting (The rule does not apply to agency traffic).
    • Targeting - agencies.
  5. [Optional] disable the Ruleset status (blue: enabled; dray: disabled.)
  6. If you selected Targeting - agencies

    RulesetAgency_us-en.jpg

    1. Select one agency.
    2. If you selected a transparent agency select:
      • Media sources: Select at least one media source. 
      • Campaigns: If you only selected one media source, select one or more or all campaigns.
    3. Continue to step 8. 
  7. If you selected Targeting:

    RulesetValid_us-en.jpg

    • Media sources: Select at least one media source. 
    • Campaigns: If you only selected one media source, select one or more or all campaigns.
  8. Click Validation rule settings targeting/Validation rule settings - targeting for agencies. 
    The rule type list displays.

    validation_rule_list.png

  9. Select a rule type and configure it using the rule type instructions that follow.
    You can configure one or more rule types.
    You cannot select the same rule type more than once. 
  10. When you have configured the rule types, click Save


Add rules

To add a campaign-name rule:

  1. Select Campaign Name
  2. Select an operator: choose from Begins with, Ends with, or Includes 
  3. Enter a campaign name string.
  4. Click Add Rule.

To add a device-type rule:

  1. Select Device Type: Use the Device type rule to exclude unwanted device types. 
  2. Select operator: Not contains.
  3. Enter the Device Type to exclude. Device names are case sensitive. You can enter multiple device names by using a delimiter between types. Example: iPhone7;iPhone6;
  4. Click Add Rule.

To add a Geo rule:

  1. Select Geo:
  2. Select Countriesselect one or more countries.
  3. Select (optional) Cities: if a single country was selected, select one or more cities
  4. Click Add Rule.

To add an OS-version rule:

  1. Select OS Version:
  2. Select an operator: 
  3. Select the OS versions as needed 
  4. Click Add Rule

Campaign target-validation raw-data reports

Targeting validation reports contain the list of invalid installs and their associated in-app events. The reports contain the fields found in raw data and have the following additional fields:

  • Reject reason value: Ruleset ID that caused the reject
  • Reject reason: Rule that caused the reject

The following raw data reports are available:

Campaign target-validation reports
Report name Description Organic Non -organic Pull API name
Invalid installs List of non-compliant installs attributed to organic Yes Yes

invalid_installs_

report

Invalid in-app events List of in-app events generated from non-compliant installs attributed to organic Yes Yes

invalid_in_app_

events_report

Invalid installations postbacks List of non-compliant install postbacks sent to the media source that brought the app user Yes Yes N/A

 You can download the targeting validation reports to do so, go to Reports > Export data. The reports are also available using Data locker and Pull API

Protect360 custom fraud rules

Protect360 consists of native and custom rules for detecting fraud. Custom rules are used to enhance Protect360's ability to:

  • Detect fraudulent installs and to block their attribution
  • Identify hijacked installs and to correct the attribution 

Rules are based on:

  • Click time to install time (CTIT)
  • Customer user ID
  • App version

By blocking the attribution, data in AppsFlyer is not distorted (usually inflated) by fraudulent installs enabling you to use the attribution data to make data-driven marketing decisions.

Agency traffic: If an advertiser defines a Protect360 custom rule, the rule also applies to agency generated traffic. 

 Notes

  • Attribution blocking does not prevent the user from using the app. If needed, you can use the blocked install raw data reports, to get the list of app users to be disabled. 
  • Protect360 applies to install conversions only, meaning that it does not apply to retargeting campaigns.

About Protect360 rules

Custom rules are contained in rulesets that you define for each app. You can use one or both ruleset types. The ruleset types available are:

  • Business customization (app version and customer user ID) 
  • Time to install (CTIT)

The following sections contain details about each ruleset type and use case examples. 

Business customization ruleset

You can define two business customization ruleset for each app. Business customization rulesets check that the:

  • App version is not listed in the rule (app versions update daily.)
  • Customer user ID is not missing

The use of Business customization rulesets is illustrated in the example that follows.

 Example: Business customization ruleset

App version rule

The ruleset screenshot that follows contains three rules 1, 2, and 3 relating to the app version followed by a table containing use cases and results.

App version rules

InstallValiation.png

App version rule: Use cases and results
User App version Rule test result (Pass/block)
A 189 Pass
B 177 Blocked by rule 2
C 100 Blocked by rule 3


The ruleset screenshot that follows contains the rule to ensure that the install contains a customer user ID followed by a table containing use cases and results

CustomerUserID.png

Customer user ID: Use cases and results
User Customer user ID Rule test result (Pass/block)
A 34324234 Pass
B  

Block: Customer user ID Is Empty (missing)

C 3241234dsaf Pass

Time to install (CTIT) minimum duration ruleset

  • One or more CTIT rulesets can be defined.
  • When using multiple CTIT rulesets, they are differentiated by media source and campaign. The CTIT ruleset with the greatest granularity (most specific) is applied when examining the install for compliance.
  • A different CTIT can be set for different geos (country and city) in each ruleset. 

The use of the CTIT ruleset is illustrated in the example that follows.

 Example: CTIT ruleset

The tale contains three CTIT rulesets defined for an app. 

CTIT rulesets
CTIT
ruleset
Media source Campaign Minimum CTIT duration
1 All All 30 seconds
2 Ad_Network_A All 50 seconds
3 Ad_Network_A C1 20 seconds

The table that follows contains three use cases A, B, and C. Using the rulesets above Protect360 selects the applicable CTIT ruleset based on granularity and then tests if the CTIT complies with the rule. 

CTIT: Use cases and results
User Media source Campaign Install CTIT Applicable CTIT
ruleset
Ruleset Pass/block
A Ad_Network_C BB 40 seconds 1 Pass
B Ad_Network_A ZZ 6 seconds 2 Block: less than 50 seconds
C Ad_Network_A C1 40 seconds 3 Pass

Protect360 examines each install and processes rule types in the following sequence:

  1. Business customization
  2. Time to install
  3. Protect360 native rules 

For each rule, Protect360 determines if the install either passes or is blocked by the rule. A blocked result means the install is fraudulent and is not attributed. Protect360 halts examining after the first blocked result.

Set Protect360 rulesets

 Caution

Use the custom rules only after you have read about them in this document to avoid blocking legitimate installs in error.

The Protect360 ruleset types that can be selected in AppsFlyer are:

  • Protect360 - time to install: block installs where the click-time-to-install (CTIT) is less than a minimum duration threshold. The threshold range is 1-60 seconds. Different thresholds can be set for different countries. The granularity is defined by media source and campaign. 
  • Protect 360 - business customization: block installs based on:
    • App version
    • Existence of customer user ID.

Select the ruleset type to view the configuration procedure here:

Time-to-install ruleset

This section contains the procedure to create time to install rulesets. Before defining the ruleset, read the two consideration paragraphs that follow. 

Considerations about media source and campaign:

  • Self-reporting networks and agencies are not included in the media source drop-down list.
  • Only active media sources and campaigns display. Active means that there was at least one impression, click, or install during the past month associated with the media source/campaign.
  • Where Media source=All the ruleset applies to the current active media source campaigns and future campaigns. This excludes self-reporting networks and agencies.
  • Where Campaign=All the ruleset applies to both existing and future campaigns.
  • Where multiple media sources are selected AppsFlyer sets Campaign=All.
  • AppsFlyer enforces ruleset granularity logic meaning you are not able to define rulesets that disregard the logic.

Considerations about CTIT and countries:

  • In the countries filter when you select All or All remaining countries, you cannot add more CTIT rules to the ruleset
  • Up to 20 CTIT country rules can be contained in the same ruleset.

To setup up a Protect 360 time to install ruleset:

  1. Go to Configuration > Validation Rules.
    The Validation Rules window opens.
  2. Click Add Ruleset.
  3. Complete the Ruleset name (free text)
  4. (optional) Disable the ruleset status (blue: enabled; gray: disabled).
  5. Select Ruleset TypeProtect 360 - time to install.
  6. Media source: Select one or more, or all media sources. 
  7. Campaign: If you only selected a single media source then select one or more, or all campaigns. 
  8. CTIT in seconds: Set from 1-60 seconds.
  9. Countries: Select one or more, or all countries.
  10. Click either:
    • Add Rule: To add the rule and to create an additional rule.
    • SaveThe ruleset is saved.

Business customization ruleset

Create rulesets for app version and customer user ID.
Note: Create a separate ruleset for each type of rule. That is one ruleset for app version and another ruleset for customer user ID.

To setup Protect360 business validation rulesets:

  1. Go to Configuration > Validation Rules.
    The Validation Rules window opens.
  2. Click Add Ruleset.
  3. Complete the Ruleset name (free text - recommended to indicate in the name if it is app version or customer ID validation)
  4. (optional) Disable the ruleset status (blue: enabled; dray: disabled).
  5. Select Ruleset Type: Protect 360 - Business customization.
  6. Select one validation rule-setting type:
    • App version: Select from including and below or is equal to and enter select a version number.
      To include additional version numbers click Add Rule.
      --OR-- 
    • Customer user ID:
      Select Is missing (means that installs without a Customer user ID will be blocked)
  7. Click Savethe ruleset is saved.

Blocked installs

Blocked installs are shown in the Protect360 dashboard. In AppsFlyer, go to Dashboard > Protect360.

In the Protect360 dashboard, blocked installs from custom rules display as follows:

  • Validation rules:
    • Blocked installs: Installs blocked by Protect360 business customization rules
    • Blocked attribution: Installs, that due to the time to install rules meant that the install status changed from fraud to the real media source

Blocked installs raw-data reports

Blocked installs from Protect360 validation rules are contained in Protect360 Blocked Fraud Reports.

The following Protect360 raw data reports can be downloaded. In AppsFlyer, go to Reports > Export Data.

  • Blocked Installations
  • Blocked In-App Events
  • Blocked Clicks
  • Blocked Installations Postbacks

The following fields contain information relevant to the blocking: 

  • Blocked Reason Rule
  • Blocked Sub Reason
  • Blocked reason value: Additional information regarding the block. Example: Site ID
Was this article helpful?