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.
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:
|
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:
|
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.
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. |
|
| No |
Deprecated starting June 7, 2021. Use min_revenue and max_revenue
|
||
| event_counter | Yes |
Integer
|
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 |
AppsFlyer uses this to derive and set the install date as follows:
|
| postback_sequence_index |
Yes, but only relevant for SKAN 4 |
Integer:
|
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:
- In AppsFlyer, go to Settings > SKAN Conversion Studio.
- Click options (⋮), select Upload decode mapping file.
- 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.
- Do one of the following:
- Click Drag & drop file.
- Upload updated mapping file.
- Follow the instructions in the user interface to upload the file.
- Turn on SKAN measurement.
- 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. - 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.
You can correct this by formatting the cells in Excel.
To format the spend amounts without a 1000 comma or $ symbol:
- Select the cells to be formatted.
- Right-click, select Format cells.
The format cells window opens. - Select Number.
- Clear Use 1000 separator (,).
- (Optional) Set the number of Decimal places. The default is 2. The maximum permitted is 5.
- 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
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.
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.