Traffic Raw Data - GetLinkfire/raw-data-documentation GitHub Wiki
Traffic Raw Data
This report provides data at the highest possible granularity about the performance of a link, including details on its traffic (visits, clickthroughs, video plays, etc) and conversions driven by the link at one of our partners, such as tracked streams, purchasing a ticket at Ticketmaster or subscribing to an Apple Music plan. Please note that this report does not cover YouTube and Apple Music streams. Due to anonymization processes, YouTube and Apple Music streams have a different format. Separate reports for these cases are also available.
Linkfire already process this data to generate visualizations and insights on our platform. However, despite the platform providing in-depth and ready-to-use analysis, the untreated data has several potential applications. For this reason, Linkfire offer the option of receiving data in its raw state.
The reports are available on a daily, weekly or monthly basis, depending only on the client’s needs.
Types of action
In this report there are three different types of records that are defined in the field "type":
- "pageview"
Represents a visit to the link. It contains information about the visitor (location, referrer, device, etc.) and about the link itself.
- "event"
Represents an action performed within the link page.
- "conversion"
Represents a conversion from one of our partners with one of our links as the referrer.
Please be aware that the conversion data available at the delivery time might be incomplete. Depending on the partner, we can receive conversions up to 60 days after the fact, and therefore, depending on the delivery cadence, it is possible that validated conversions will not be added to the report.
Best practices for processing and analyzing the data.
As mentioned above, the report has three different types of data, each with specific details that must be taken into account during processing and analysis:
- "pageview"
This type is very straightforward, one "pageview" record = one visit to the link.
An interesting point to note are the fields "visitortoken" and "visitoruid" (used in all three types of records). Both of these fields serve as unique identifiers for users. However, "visitortoken" has a lifespan of 10 minutes, while "visitoruid" lasts for 6 months. These fields can be valuable for matching reports from other sources and for identifying both unique and returning visitors."
- "event"
These actions may or may not have been initiated by the user, so it is essential to distinguish how the events were triggered. This can be achieved through the "eventaction" field:
- eventaction = "manual" -> The user manually clicked on the item that triggered the action;
- eventaction = "play" -> The user manually clicked on a video to watch it;
- eventaction = "d2s" or "fallback-redirect" -> The user was automatically redirected (should not count as active clickthrough).
- "conversion"
A conversion record may represent multiple actions with varying meanings carried out at one of our partner sites, from streams to purchases. A good start is to use the "convsource" field, which specifies the source of the conversion, such as "applemusic", "spotify", "ticketmaster", etc. To filter specific items we can use the fields "convcategory", "convdescription" and "convaction".
Fields
| Field Name | Description | Example |
|---|---|---|
| activity | Activity ID (string) added by the marketer to the link. Max 50 characters. | eveningpromotion, giveaway |
| artists | The name of the artist associated with the link. | Music Band |
| asset | The type of asset where the activity took place. | landingpage, bridgepage, widget |
| boardid | UUID of the board the visited link is in. | a1c50793-2c2a-4809-ae23-3204a4584cad |
| boardname | Name of the board where the link is placed. | music-label |
| browser | Name of visitor's browser as identified through the use of Browscap decoded from the user agent. | Chrome, IE, Facebook App, Safari |
| campaigntype | The type of link used. | Music, Content |
| channelid | UUID of the marketing channel used by the marketer. | d8b8bb4f-4c47-11e6-9fd0-066c3e7a8751 |
| channelname | The name of the marketing channel used by the marketer when promoting the link. | Instagram, YouTube Description, Facebook |
| channeltype | The category of the marketing channel used by the marketer when promoting the link. | Owned, Paid, Original |
| city | Name of visitor's city as decoded from IP using Maxmind GeoIP. | Copenhagen |
| convcategory | Category of the conversion. | Music, Movies, Tickets |
| convdescription | Optional additional description about the conversion, for example Ticketmaster show venue. | Royal Arena |
| convid | The product ID as defined by the merchant where the conversion took place. | Defined by merchant |
| convidsecond | Optional additional ID used for identification, such as user ID. | Defined by merchant |
| convname | Name of the product, such as the track, album or ticket in the transaction. | Excellent Musical Music Track |
| convreference | A reference to the specific transaction provided by the merchant. | Defined by merchant |
| convsource | Name of the merchant/service where the transaction took place. | itunes, amazon, applemusic |
| convtoken | The affiliate token (if any) to which the transaction was attributed. | 1001l9mr |
| convtype | The type of the product in the transaction. | Song, Video, Playlist |
| convvalue | A value assigned to the transaction, such as purchase value. | Defined by merchant |
| convvaluesecond | Optional additional value such as the commission value of a purchase. | Defined by merchant |
| convvaluetype | Identifies the format of the value. | currency |
| convvalueunit | The unit of the value. | USD, GBP, seconds |
| countrycode | ISO 3166-1 alpha-2 country code of the visitor. | DK |
| created | UTC timestamp for the action in ISO8601 format. | 2019-01-07 23:59:45.084 |
| device | The type of device used by the visitor. | mobile, desktop, tablet |
| eventaction | The type of action taken by the visitor. | manual, d2s, play |
| eventcategory | The context in which the visitor's action happened. | service, widget, player |
| eventcategorytype | The type of the item on which the visitor performed an action. | play, goto, download |
| eventlabel | The name of the item on which the visitor performed an action. | applemusic, spotify, deezer |
| eventvalue | N/A | N/A |
| N/A | ||
| linkid | UUID of the visited link. | 13591d85-bd99-469a-812d-4088d6320a91 |
| linkurl | The URL of the link. | artist.lnk.to/album |
| newsession | Indicates whether this pageview is the first pageview of the session (matching the actual visitortoken). | true, false |
| os | The visitor's operating system. | iOS, Android, Windows 10, Windows 7 |
| params | URL parameters included in the full URL of the visit, as json. | {'fbclid': 'IwAR0S5crLkOb1zCZ6ImMmj8Zs'} |
| referrer | The full URL of the HTTP referrer. | http://m.facebook.com |
| tags | The tags added to the link(s) | 1960s, Live, Pop |
| toplevelreferrer | Root domain of the HTTP referrer. | youtube.com, facebook.com |
| type | The action taken by the visitor. | pageview, event, conversion |
| N/A | ||
| visitortoken | Unique visitor token to identify and correlate visitor actions. Has a 10 minute lifetime. | 70289507v161c9c3c759e2e534859b73 |
| visitoruid | Unique visitor token to identify and correlate visitor actions. Based on a cookie with 6 months lifespan. Note: this is PII. | 5b303fgcda39e8.46766248 |
| linkscanningsource | Depending on linkscanningtype, a URL,ISRC,UPC or bandsintown reference | https://open.spotify.com/track/4uLU6hMCjMI75M1A2tKUQC?si=bdn7MR-zS7K3w-LdKiZR2g |
| linkscanningtype | The type of source used when creating the link. | URL |
| convusdvalue | The value of 'convvalue' converted to USD | 9.99 |
| convusdvaluesecond | The value of 'convvaluesecond' converted to USD | 0.99 |
| orgid | ID of the organisation which the board and link belongs to. | cf5d408c-633d-416a-9df7-3af93b5dc1f5 |
| orgname | Name of the organisation which the board and link belongs to. | Lunarhub Records |
| isrcs | For links associated with a track, the ISRC of the track. | USBSR0930647 |
| upcs | For links associated with an album, the UPC of the album. | 884483917087 |
| convaction | Action taken on the merchant/service by the user. | Play, Purchase, PreSave, Add to playlist |
| eventblocktype | The type of block an action took place on (Bio links only) | ExternalLinks, SocialLinks, Videos, Images |
| eventbuttontext | The custom text added to a Bio link button. | Visit my store here |
| artistexternalid | Artist ID provided by label (if applicable) | 123456789 |