Custom conversion value decode for SKAdNetwork

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

SKAdNetwork_-_Custom__1_.png

Decode SKAdNetwork custom conversion value 

Advertisers use the custom conversion value decode solution as an alternative to the AppsFlyer SKAdNetwork measurement types available in the user interface. If you select decode custom conversion, it means you are responsible for setting updateConversionValue according to your app logic. 

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

Custom conversion value—decode

Implementation of custom conversion value requires that you upload a CSV file containing your conversion value 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.
  • Conversion value 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. 
  • On receipt of a postback from iOS, the conversion value is decoded into events as illustrated in the examples. 
  • The install time is derived using the postback Events have the same time as the install time.
  • In order to best understand how to prepare the schema, review the mapping scenarios that follow. 

Decode mapping—example scenarios

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 purpose of 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.
conversion_
value
event_
name
event_
value
event_revenue
_usd
scale event_
counter
hours_from_
install
1 af_purchase {abc} 2   1 24
2 af_purchase {def} 3   3 24
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) 5   2 36
62 event_a {klm}     3 72
Example: Decode mapping
Example A: Conversion value 1
event_name revenue event_value
install    
af_purchase 2 {abc}
Example B: Conversion value 2
event_name revenue event_value
install    
af_purchase 3 {def}
af_purchase 3 {def}
af_purchase 3 {def}
Example C: Conversion value 21
event_name 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 revenue event_value
install    
af_purchase 5 {fgh}
af_purchase 5 {fgh}
event_a   {klm}
event_a   {klm}
event_a   {klm}

Scenario with revenue ranges and foreign currency

  • For a given conversion value (CV), set revenue in USD from $0-$10,000.
  • The revenue associated with a CV is fixed.
  • In the app, the developer sets the CV using the most recent cumulative purchase amount in USD. This means for each transaction they convert from local currency to USD.
  • The tables, in the figure that follows, contain an example CSV mapping from 1-4 with the associated total (cumulative purchase revenue for each CV) and the user journey. 
  • The user makes 5 purchases, each for a different amount in Euro. These are converted to USD and display in the cumulative total.
  • The CV is set using the cumulative value. In this example, the cumulative purchase revenue is rounded up. 

mceclip0.png

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 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).
Decode schema
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  
event_revenue_usd No Integer, Floating

Revenue generated in USD.

If no revenue is associated with the event set to blank not 0.

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. 

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 USD amount reported is duplicated according to the counter. See the examples. 

hours_from_install Yes Integer

Hours elapsed since the install. AppsFlyer uses this to derive and set the install time as follows: install date = postback timestamp - (max hours_from_install + 48h). Event times are set equal to the install time

Upload conversion value schema file

Before you begin:

Prepare the conversion value schema CSV file.

To enable SKAdNetwork measurement using custom measurement:

  1. In AppsFlyer, go to Settings > SKAdNetwork settings. 
  2. Select Custom measurement.
  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 SkadNetwork measurement.
  6. Click Save changes. 
    Note: For the next 48 hours data in the dashboard is doubtful. 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 are able to correctly consume postbacks. 

Troubleshooting the csv upload errors file

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 you save 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

mceclip2.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 character 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?