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

Related reading: SKAN Conversion Studio (SKAdNetwork settings)

Decode SKAN conversion value

Advertisers use conversion value decode as an alternative to using options avaialble in Conversion Studio. If you use Decode, it means you are responsible for setting updateConversionValue 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, who 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 conversion values 1-63. 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 Facebook integration, subject to the Facebook-specific rules detailed in the next section. 

Decode mapping scenario rules

Consider:

  • Conversion value range: 1-63
  • 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.

Facebook-specific rules

If you integrate with Facebook, 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: Facebook doesn't consider this value. [Best practice] Populate it with a value of 1. 
conversion_
value
event_
name
event_
value

min_revenue

(not -inclusive)

max_revenue (inclusive) scale 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: Decode mapping
Example A: Conversion value 1
event_name skad_revenue

min_ revenue

max_revenue

event_value
install        
af_purchase 1.5 0 3 {abc}
Example B: 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: 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: 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. Example decode CSV.
  • Don't use the following characters as the first character in a column: =+-, and @ (edited).
 
Column  Mandatory value  Content Details
conversion_value Yes Integer value 1–63

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

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

 

scale No Leave empty Reserved for future use. Leave empty. 
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 event_value_usd = 3 and event_counter = 4 the total revenue reported 3 X 4 = 12.

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 time as follows: install date = postback timestamp - (max hours_from_install + 36h). Event times are set equal to the install time

 

Upload conversion value schema file

Before you begin:

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

To enable SKAN measurement using custom deocde measurement:

  1. In AppsFlyer, go to Settings > SKAN Conversion Studio. 
  2. Click options (⋮), select Upload custom decode mapping file
  3. Do one of the following:
    • Click Drag & drop file.
    • Upload updated mapping file.
  4. Follow the instructions in the user interface to upload the file. 
  5. Turn on SKAN measurement.
  6. 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. 
  7. 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.
Was this article helpful?