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:

https://exampledsp.com/rolling-stones-official/blue-lonesome/?lf=e96a86726be351a90fdf0535e8c50c0e

The default session id parameter can be altered if it conflicts with existing parameters.

File

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:

filename.json.gz

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

Delivery destination

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

Data

Principles

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
ProductId
ProductName
ArtistId
ArtistName
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
StreamDurationTime
StreamDurationUnit		Seconds
PurchaseValue
PurchaseValueCurrency
CommissionValue
CommissionValueCurrency
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