File reporting - GetLinkfire/Integrations GitHub Wiki
Linkfire event attribution through file reporting
When entering an attribution partnership with Linkfire, we'll add an extra URL parameter when referring traffic to you. This parameter contains a session id which enables us to attribute the conversion events back to the link and session where the referral happened.
The session id is cookie based and unique for every link and channel. It has a lifetime of 10 minutes.
Example of a Linkfire session id as a URL parameter:
The default session id parameter can be altered if it conflicts with existing parameters.
Our preferred file formats, in order of priority, are:
- Parquet (external documentation)
Encoding and compression
Files in JSON or CSV format should be encoded as UTF-8 and gzipped. The original file extension should be available as part of the compressed file name. Example:
Reporting time range
Data should at least be delivered in daily intervals, preferably as close to midnight in UTC as possible. Delivery multiple times per days, e.g. hourly, is preferred.
Folder schema and file names
Files should be delivered to folders corresponding to the delivery time. Files names should include report date and timestamp for the report generation. Date and time should use the ISO 8601 standard and be in UTC. Example:
2021-01-02/2021-01-01_2021-01-02T071107Z.parquet [delivery date]/[report date]_[report generation date and time]
In cases where one delivery can consist of several files, there should be one folder per delivery (e.g. day or hour) containing all files for that delivery. Additionally, an empty text file named
_SUCCESS - added after all data was written - will help recognize that the delivery is complete. Example:
2021-01-02/2021-01-01_2021-01-02T071107Z/part-r-0000.parquet 2021-01-02/2021-01-01_2021-01-02T071107Z/part-r-0001.parquet ... 2021-01-02/2021-01-01_2021-01-02T071107Z/part-r-0042.parquet 2021-01-02/2021-01-01_2021-01-02T071107Z/_SUCCESS
- Explicit is better than implicit – If something can be stated explicitly in the data that is much preferred over us arriving at the same result by means of deduction
- Use dedicated fields rather than multi-purpose
- One row of data should represent one event and not one session with several events
Events and parameters of interest
These are some of the events and parameters that Linkfire and its clients would like to track as result of Linkfire directing traffic. We’re only interested in the data that Linkfire refers.
|Track||Stream, Qualified stream (30s), Stream duration, Favorite, Share, Add to playlist, Save to library, Purchase|
|Album||Favorite, Share, Save to library, Purchase|
|Artist page||Follow, Share|
|Movie, video||Stream, Qualified stream (30s), Play duration, Favorite, Share, Add to playlist, Save to library, Purchase|
|Version||Required||1.0||Version of the data schema used|
|Timestamp||Required||YYYY-MM-DDThh:mm:ssZ||Date and time in UTC where the event happened. Date and time should be in the ISO 8601 standard|
|VisitorToken||Required||Linkfire session identifier|
|Event||Required||Stream, QualifiedStream, StreamDuration, Purchase, Favorite, Share, AddToPlaylist, SaveToLibrary, Subscribe|
|ContentCategory||Required||Music, Movie, Ticket, Merchandise|
|ContentType||Required||Track, Album, Playlist, Artist page, Video, Ticket, T-shirt, Membership|
|StreamTotalDuration||Total duration of the streamed content in seconds|
|StreamDurationPercentage||Percentage of the track streamed before being stopped or skipped|
|MerchandiseType||Type of merchandise, e.g. t-shirt, poster|
|ShareLabel||Description of the Share event, e.g. service shared to or way of sharing|
|AddToPlaylistLabel||Name of the playlist|
|UserSubscription||Whether the user was a trial, free, premium user|