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.
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
Implementing 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.
- Upon receiving a postback from iOS, the conversion value 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
- 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.
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.
Decode csv file specification
Conversion values are mapped to one or more in-app events.
- 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:
|conversion_value||Yes||Integer value 1–63||
The same conversion value can be listed more than once. See the examples for further explanation.
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.|
|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.
If you populate min_revenue: max_revenue must have a value greater than 0.
See min_revenue for the explanation.
Deprecated starting June 7, 2021. Use min_revenue and max_revenue
|scale||No||Leave empty||Reserved for future use. Leave empty.|
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.
AppsFlyer uses this to derive and set the install time as follows: install date = postback timestamp - (max hours_from_install + 24h). 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 SKAdNetwork measurement using custom measurement:
- In AppsFlyer, go to Settings > SKAdNetwork settings.
- Select Custom measurement.
- 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 SkadNetwork measurement.
- 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.
- 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.
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.