SKAN CV decode (map your CV to events)

At a glance: AppsFlyer decodes and transforms the conversion value set by you into events. The events are used to populate the SKAN dashboard, raw data, and postbacks to partners.

SKAdNetwork_-_Custom__1_.png

Decode SKAN conversion value

Advertisers use conversion value decode as an alternative to using options available in Conversion Studio. If you use Decode, it means you are responsible for setting updatePostbackConversionValue according to your app logic. 

Apart from setting the conversion value (CV) in the app, the remainder of the flow, features, and reporting options are the same as those described in the SKAN solution guide. This means that at the expiry of the activity window (controlled by you), iOS sends the postback to the ad network, which forwards it to AppsFlyer. AppsFlyer decodes the CV according to your mapping into events processed just like decoded CVs set by the SDK.

Custom conversion value—Decode

Implementing custom CV decode requires uploading a CSV file containing your CV mapping to the AppsFlyer platform. 

Decode mapping principles

  • Provide decode mapping for fine conversion values (1-63), and coarse conversion values (low, medium, and high) for windows 1-3. It's not mandatory to map the entire range of values. For example, you can map values 1, 2, 10, and 43.
  • CV 0 is always mapped to install. You can't set it. 
  • The mapping table is uploaded to AppsFlyer in a CSV file. You can upload an updated mapping table as needed. 
  • Upon receiving a postback from iOS, the CV is decoded into events, as illustrated in the examples. 
  • The install time is derived using the postback arrival time. 
  • Events have the same time as the install time.
  • To best understand how to prepare the schema, review the mapping scenarios that follow. 
  • Custom in-app events names are allowed.
    • Meaning you send new event names, even if they haven't ever been sent by the SDK.
    • You can map the in-app events to ad network in-app events.
    • This is also true for Meta ads integration, subject to Meta-specific rules detailed in the next section. 

Decode mapping scenario rules

Consider:

  • Fine conversion value range: 1-63
  • Coarse conversion value range: Low, medium, and high
  • A given conversion value maps to one or more in-app events specified by you. In-app events have optional parameters.
  • For the examples: Assume that the install date is Feb 1 at 08:00.
  • The table that follows is an example decode mapping table. Its structure is similar to that of the CSV file required. Following the table are the events generated as a result of the decoding process.
  • An install event is always generated, irrespective of your mapping.
  • Revenue measurement:
    • Revenue is in USD.
    • A given conversion value has a revenue range bounded by  min_revenue and max_revenue. 
    • In aggregated reports and dashboards, revenue is calculated as the average of the range. Example: min_revenue=4 and max_revenue=10. The calculated revenue is 7.
    • Raw data reports include the calculated revenue (skad_revenue), min_revenue, and max_revenue.

Meta-specific rules

If you integrate with Meta ads, adhere to the following rules:

  • Min and max revenue values for a given conversion value must be different. Meaning not equal. 
  • Values mustn't overlap and must be in consecutive order as illustrated for conversion_value 1-2 and 62 in the table that follows. 
  • event_counter: Meta ads doesn't consider this value. [Best practice] Populate it with a value of 1. 

Example: Decode mapping

conversion_
value
event_
name
event_
value

min_revenue

(not -inclusive)

max_revenue (inclusive) event_
counter
hours_from_
install
1 af_purchase {abc} 0 3 1 24
2 af_purchase {def} 3 10 3 36
21 event_a       1 24
21 event_b       3 24
21 event_c {xyz}     2 24
21 event_d       1 24
21 event_e       1 24
21 event_f       1 24
21 event_g       1 24
62 af_purchase {fgh) 10 17 2 72
62 event_a {klm}     3 72

Example A: Fine conversion value 1

event_name skad_revenue

min_ revenue

max_revenue

event_value
install        
af_purchase 1.5 0 3 {abc}

Example B: Fine conversion value 2

event_name skad_revenue min_revenue max_revenue event_value
install        
af_purchase 6.5 3 10 {def}
af_purchase 6.5 3 10 {def}
af_purchase 6.5 3 10 {def}

Example C: Fine conversion value 21

event_name skad_revenue min_revenue max_revenue event_value
install        
event_a        
event_b        
event_b        
event_b        
event_c       {xyz}
event_c       {xyz}
event_d        
event_e        
event_f        
event_g        

Example D: Fine conversion value 62

event_name skad_revenue min_revenue max_revenue event_value
install        
af_purchase 13.5 10 17 {fgh}
af_purchase 13.5 10 17 {fgh}
event_a       {klm}
event_a       {klm}
event_a       {klm}

Decode csv file specification

Conversion values are mapped to one or more in-app events.

File rules

  • Format: CSV file
  • Maximum number of rows: 640 + header row; total 641.
  • The header row must include all the column names exactly as they display here. Best practice: Use the example file attached as a template. See sample decode CSV files for SKAN 3 and SKAN 4.
  • Don't use the following characters as the first character in a column: =+-, and @ (edited).

Decode csv file specification

Column  Mandatory value  Content Details
conversion_value

Yes, for:

  • SKAN 3 and below
  • SKAN 4 where postback_sequence_index is 0
Integer value 1–63

The same fine conversion value can be listed more than once. See the examples for further explanation. 

coarse_conversion_value

Relevant only for SKAN 4

String:

  • low
  • medium
  • high

The same coarse conversion value can be listed more than once.

event_name Yes String

In-app event. It does not have to be an event that already exists in AppsFlyer.

Note! In-app event names are case-sensitive.

[Best practice]: Event name for revenue af_skad_revenue. 

event_value No String String set by the developer containing data to be decoded by the advertiser in their systems. Typically this is in the format of a JSON. 
min_revenue

No

 

Integer or  floating

Use the min_revenue and max_revenue to set a revenue range in USD.

  • If you don't want to associate revenue with a conversion value, set min_revenue and max_revenue to blank.
  • The value set in min_revenue is not inclusive. Meaning greater than 0. Similar to 0.0001
  • The value set in max_value is inclusive.
  • Example: If min_revenue is 0 and max_revenue is 4, this means the range is 0.0001-4
  • max_revenue must be greater than min_revenue

Note! If you generate the file using Excel, before saving, change the column format to comma and not currency to avoid Excel embedding a $ symbol in the CSV file.

max_revenue No  

If you populate min_revenue: max_revenue must have a value greater than 0. 

See min_revenue for the explanation. 

event_revenue_usd No  

 

Deprecated starting June 7, 2021. Use min_revenue and max_revenue

 

event_counter Yes

Integer 

 

  • Number of times the event is duplicated on decoding. Typically it represents the number of times the user performed a given action.
  • Minimum value 1.

Example: If the user performed a given event 5 times, then 5 events are generated.

Considerations: If you send revenue, the total USD amount reported is multiplied by the value in event_counter. Meaning if min_revenue = 0, max_revenue = 3, and event_counter = 4 the total revenue reported 1.5 X 4 = 6.

See the examples.

hours_from_install Yes Integer
  • Hours elapsed since the install
  • Minimum value: 1
  • Maximum value: 1512 (63 days) 
  • The value for all rows of a given conversion_value must be identical. Meaning different values for different conversion values is permitted. 

AppsFlyer uses this to derive and set the install date as follows:

  • If the postbacks are SKAN V4, the install date formula is: Install date = postback arrival time - [accumulated window length] - [average postback delay].
    • Postback 1: install date = postback arrival time - 48h - 36h
  • If the postbacks are SKAN V3, the install date formula is: Install date = postback arrival time - 36 hours - [average last-active range]. 
    • The default [average last-active range] is 12 hours.
    • For a conversion value of 0, the average last-active range is set to 0.
postback_sequence_index 

Yes, but only relevant for SKAN 4

Integer:

  • 0
  • 1
  • 2

For fine value, only the value of 0 can be received.

Upload conversion value schema file

Before you begin:

  • Prepare the conversion value schema CSV file.
  • If you integrate with Meta ads and measure revenue, verify that your schema complies with rules relating to Meta. If you don't, Meta ads can't interpret the schema. 

To enable SKAN measurement using decode measurement:

  1. In AppsFlyer, go to Settings > SKAN Conversion Studio. 
  2. Click options (⋮), select Upload decode mapping file.
  3. If you haven't yet upgraded to SKAN 4, choose to upload a file for SKAN 4 or pre SKAN 4. Once you upgrade to SKAN 4, the choice for other versions is unavailable.
  4. Do one of the following:
    • Click Drag & drop file.
    • Upload updated mapping file.
  5. Follow the instructions in the user interface to upload the file. 
  6. Turn on SKAN measurement.
  7. Click Save changes. 
    Note: For the next 48-72 hours, data in the dashboard is ambiguous. Meaning due to iOS timer issues, we can't be sure if the decode mapping matches the encode mapping used by you. 
  8. Ensure that you have mapped your in-app events to those used by partners so that they can consume postbacks correctly. 

Troubleshooting the CSV upload errors file

Upload error messages

One or more values in the file don't match the required format: The file format was changed starting June 7, 2021. Verify that your file format matches the example in this article. 

Using Excel to format the event_revenue_usd column

When using Excel/Google sheets to create a CSV file, the event_revenue_usd column must be formatted correctly before saving the file as a CSV file. 

After saving the CSV file, verify that the content is formatted correctly. Note: Don't use Excel to do the verification; rather, use an editor

Formatting event_revenue_usd cells in Excel

Excel usually formats value cells with a comma to separate the thousands, as shown in the figure. This format is not suitable for upload CSV files. You must also remove the $ symbol. 

mceclip0.png

You can correct this by formatting the cells in Excel. 

To format the spend amounts without a 1000 comma or $ symbol:

  1. Select the cells to be formatted.
  2. Right-click, select Format cells.
    The format cells window opens.
  3. Select Number.

    Formatnumbers.png

  1. Clear Use 1000 separator (,). 
  2. (Optional) Set the number of Decimal places. The default is 2. The maximum permitted is 5. 
  3. Click OK.
    The cells are formatted correctly.

Visual inspection of the CSV file without Excel

To examine the content of the CSV file, use an editor to view the file. 

  • Windows: Notepad, Notepad++
  • macOS: TextEdit

The following contains a screenshot of the example CSV file displayed in an editor. 

Editor view

SKCustomeEditor.png

Using an editor, examine the CSV file. Pay special attention to the following:

  • Blank spaces: Ensure that there are no leading or trailing blank spaces before or after the commas that separate the fields. In Excel, use the @trim command to remove blank spaces. 
  • event_revenue_usd: Ensure that there is neither a comma nor a $ symbol in the event_revenue_usd column.

    mceclip1.png

CSV files generated by Excel don't have commas as delimiters

If Excel creates CSV file with a semi-colon ";" or other characters as a delimiter but not a comma:

  • This occurs when your computer's regional settings are set to a language/region that is not English.
  • This issue is particularly prevalent when German is selected in the regional settings.
  • The solution differs depending on your computer operating system (macOS or Windows).
  • To resolve this issue, search for the latest guidance from Microsoft or other forums to revolve. Use the following search terms: Operating system (macOS or Windows) Excel change delimiter for CSV files.