File reporting - GetLinkfire/Integrations GitHub Wiki

Linkfire event attribution through file reporting

Attribution identification

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.


File format

Our preferred file formats, in order of priority, are:

  1. Parquet (external documentation)
  2. JSON
  3. CSV

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:

[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:


Delivery destination

See our docs regarding S3 bucket replication and how to set it up



  1. 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
  2. Use dedicated fields rather than multi-purpose
  3. 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.

Content types Events
Track Stream, Qualified stream (30s), Stream duration, Favorite, Share, Add to playlist, Save to library, Purchase
Album Favorite, Share, Save to library, Purchase
Playlist Favorite, Share
Artist page Follow, Share
Movie, video Stream, Qualified stream (30s), Play duration, Favorite, Share, Add to playlist, Save to library, Purchase
Ticket Purchase, RSVP
Merchandise Purchase
Membership Trial, subscription

Data schema

Field Required? Expected values Description
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
StreamDurationUnit Seconds
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
UDID Device Id