Retrieve report logs
Access to Equativ logs requires activation - reach out to your contact at Equativ to get access.
Overview
Equativ's standard reports (generated by the UI or the API) are ready to use and cover most reporting needs. However, you may need to inject raw data from the Equativ platform into your systems for further business analysis or data optimizations. For these cases, Equativ provides raw data extracts referred to as Equativ logs.
Definition
Logs represent the raw form of information collected whenever a call to Equativ’s servers is executed (an interaction with the Equativ servers occurred). For instance, when an ad is delivered and displayed for the user, this will be logged as an impression. Other examples of events which trigger a call to Equativ (with subsequent storage in the logs):
- clicks on an ad
- clicks on the "mute" button of a video player
Example
| LogID | CookieID | InsertionID | PageID | DateLog | CreativeId | AdvertiserId | FormatID |
|---|---|---|---|---|---|---|---|
| 4717826535145 | 5954681822332600000 | 4507588 | 98017 | 10/18/2017 10:34 | 16724752 | 177314 | 8723 |
The log above:
- is an impression log
- was executed on Oct 18th 2017 at 10h34 am (DateLog)
- was triggered by a user with CookieID=5954681822332600000
- originated from a placement with pageID=98017 and formatID=8723
- is for a creative with CreativeId=16724752, which was in an insertion with InsertionID=4507588
Log fields
A log comes with a set of columns (see example above: LogId, CookieID etc.). The columns are referred to as "log fields".
List of log fields
| Field Name | Description | Log type (direct, RTB) |
|---|---|---|
| ActionKey | Key of the action pixel | direct |
| ActionReference | Reference of the action pixel | direct |
| ActionValue | Value of the action pixel | direct |
| AdBreak | Ad Break | direct |
| AdPosition | Ad Position | RTB |
| AdvertiserId | Advertiser ID | direct |
| BrowserId | Browser ID | direct / RTB |
| CampaignId | Campaign ID | direct |
| ContentType | Content Type | RTB |
| CookieId* | Equativ Cookie ID | direct / RTB |
| CountryCode | Country Code | RTB |
| DealIds | Deal IDs | RTB |
| Dnt | "Do Not Track" browser flag; 0 - tracking allowed; 1 - tracking prohibited | RTB |
| EnvironmentType | Type of ad call | RTB |
| EventTypeId | Event type ID | direct |
| FormatId | Format ID | direct / RTB |
| IabCategory | IAB category | direct |
| ImageId | Creative ID | direct |
| ImpressionLogTime | Time of impression log | RTB |
| ImpressionType | Type of the impression | RTB |
| InsertionId | Insertion ID | direct / RTB |
| IsSecure | Is HTTPS call | RTB |
| Keywords | Keywords | RTB |
| LineSpeed | Line Speed | direct / RTB |
| LogCategory | Category of the log | direct |
| LogTimeNetwork | Date time of the log, network | direct / RTB |
| LogTimeUtc | Date time of the log, UTC | direct / RTB |
| Master | Is pageview | direct |
| MobileModel | Mobile Model | direct |
| MobileSdkVersion | Mobile SDK version | direct |
| MobileVendor | Mobile manufacturer | direct |
| NetworkId | Network ID | direct / RTB |
| OsId | OS ID | direct / RTB |
| PageId | Page ID | direct / RTB |
| PercentageViewedArea | Viewed percentage of area | direct |
| Platform | Platform | direct / RTB |
| PostalCode | Postal Code | direct |
| QuovaCarrierId | ISP ID | direct / RTB |
| QuovaCityId | City ID | direct / RTB |
| QuovaCountryId | Country ID | direct / RTB |
| QuovaStateId | State ID | direct / RTB |
| Referrer | Call referrer | direct / RTB |
| RtbVideoPlayerHeight | RTB video player height | RTB |
| RtbVideoPlayerWidth | RTB video player width | RTB |
| RuleId | Delivery rule ID | RTB |
| SamplingRate | Sampling Rate for the log extract | direct |
| ScreenHeight | Height of the screen | direct / RTB |
| ScreenWidth | Width of the screen | direct / RTB |
| SiteId | Site ID | direct / RTB |
| SmartDomainPid | Equativ Domain PID | RTB |
| Timestamp | Cache busting value | direct |
| TrackingTransactionId | Tracking Transaction ID | direct / RTB |
| UniqueLogId | Unique Log ID | direct, RTB |
| UserAgent | User Agent of the ad call | direct |
| UserId | Original value identifying the user - as passed in the uid= parameter of the ad call; see also CookieId* | direct |
| UserKeywords | User keywords | direct |
| VideoCmsId | Video CMS ID | direct |
| VideoContentCategory | Video content category | direct |
| VideoContentDistributorId | Video content distributor ID | direct |
| VideoContentDistributorName | Video content distributor name | direct |
| VideoContentDuration | Video content duration | direct |
| VideoContentId | Video content ID | direct |
| VideoContentProviderId | Video content provider ID | direct |
| VideoContentProviderName | Video content provider name | direct |
| VideoContentRating | Video content rating | direct |
| VideoContentTags | Video content tags | direct |
| VideoContentTitle | Video content title | direct |
| VideoContentType | Video content type | direct |
| VideoEpisodeNumber | Video episode number | direct |
| VideoExternalContentId | Video external content ID | direct |
| VideoSeasonNumber | Video season number | direct |
| Visit | visit counting; "visit=M" for first ad call on the page; "visit=S" for all other ad calls | direct |
| WinnerAdId | Winner A | RTB |
| WinnerAdomainCleanId | Winner Ad domain ID | RTB |
| WinnerBuyerBidId | Winner Buyer Bid ID | RTB |
| WinnerCampaignId | Winner Campaign ID | RTB |
| WinnerCreativeId | Winner Creative ID | RTB |
| WinnerDealId | Winner Deal ID | RTB |
| WinnerDspId | Winner DSP ID | RTB |
| WinnerOfferedPrice | Winner Offered Price | RTB |
| WinnerPartnerId | Winner Partner ID | RTB |
| WinnerPrice | Winner Price | RTB |
| WinnerPriceDspCurrency | Winner Price DSP Currency | RTB |
| WinnerPriceNetworkCurrency | Winner Price Network Currency | RTB |
| WinnerRuleId | Winner Rule ID | RTB |
| WinnerSeatId | Winner Seat ID | RTB |
| WinnerSmartBuyerId | Winner Equativ Buyer ID | RTB |
* The CookieId is the unique ID stored in Equativ's user identification cookie. If the ad call contained the uid= parameter (with a value), the stored CookieId will be a number conversion calculated from the uid= parameter's value (string). If both uid= and Equativ's user identification cookie are missing, the CookieId will be zero.
Specific Enums
Most of the fields contain dynamic information. For instance, the field WinnerPrice will contain what is the actual RTB winning price for the given impression.
However, some fields have a set of fixed values to be returned and thus can be considered as enums.
List of specific enums
| Enum | Values |
|---|---|
| DeviceType | MobileOrTablet = 1 PersonalComputer = 2 ConnectedTV = 3 Phone = 4 Tablet = 5 ConnectedDevice = 6 SetTopBox = 7 |
| DeviceType (aka Platform) | Unknown = 0 Desktop = 1 Mobile = 2 Tablet = 4 Tv = 8 ConnectedDevice = 16 SetTopBox = 32 GameConsole = 64 |
| EnvironmentType (aka InventoryType); currently, not functioning | Web MobileWeb MobileApp |
| ImpressionType | 0=Banner 1=In-stream Video 2=Native 3=Out-stream Video |
| OutputType | JavaScript NonRich Iframe Xml Json Vast Vast2 Vast3 |
Equativ internal enums via API
Many fields in the logs hold enums which are Equativ-internal (e. g. Insertion ID, Browser ID, Format ID etc.).
To query these enums, you can use Equativ's API. For more information, see Reporting API: get started.
Dealing with large extracts
Applying a sampling rate
The amount of information stored in logs may lead to very large log files. For instance, even when selecting only the main fields, 5 million impressions a day lead to log files (csv) of 700 MB each day.
In case of such large log files, you can apply a custom sampling rate to reduce the number of logs returned. The sampling rate is adjustable. For example, with a sampling rate of 50, Equativ will extract 1 out of 50 logs. Typically, sampling is not used for impressions and clicks but rather for large amounts of data and specifically heavy fields (e. g. referrer URL or user agent).
Get back to your service contact at Equativ to discuss your requirements and chose appropriate sampling rates.
Splitting and merging extracts with different sampling rates
The applied sampling rate always applies to an entire extract. In some cases adding a field (e. g. the referrer URL) may require a sampling rate which would not be necessary without the added field.
In this case, splitting the extract is recommended:
- extract #1: contains the main fields; full extract, no sampling
- extract #2: contains the heavy fields; some level of sampling; typically, the sampling does not impact the overall data analysis
As a result, you will get the same type of log (e. g. an impression log) in two extracts: one with the main (but not all) data and another with only the additional information about the data.
To merge them, you need to make use of the UniqueLogID field. This field holds a unique ID for each log entry. All the data in the log (e. g. referrer URL, cookieID, timestamp etc.) is associated with this UniqueLogId.
When you merge the two log entries (based on the UniqueLogId field), make sure you give priority to the non-sampled data in order to obtain the extra fields applied to the full non-sampled data.
Exporting the logs
At this time, Equativ logs are exported through a web service for log extraction which is based on a REST API:
- extract files are in csv format
- there are multiple options available, e. g., filtering per date and time, custom separator, specific timezones or filtering values for the fields (see list below)
- a scheduling service can create extracts for rolling timeframes and store the extract files in your FTP folder area
The API is not publicly available. Get back to your service contact at Equativ to obtain a one-time extract or schedule a recurrent extract stored on your FTP server.
List of available options
| Property | Value type | Description | Necessity |
|---|---|---|---|
| Enddate | Date / RelativeDate | the end date of the extract |
Required |
| ExtractField | String[] | the list of extract fields | Required |
| LogCategory | String | the log category to extract | Required |
| outputParameters | datePattern: String | the pattern of all date fields on the output generated | Optional |
| outputParameters | displayHeader: Boolean | true/false; specifies if the header will be included in the generated file (default: false) | Optional |
| outputParameters | fieldSeparator: String (regex) | a regex specifying the separator to insert between the fields (default: tabulation) | Optional |
| outputParameters | filenameTemplate: String | the file name to generate; a tag containing a relative date may be inserted in this filename; this is useful for scheduled tasks which generate different files every day, hour etc.; example: report_[CURRENT_DAY].txt; keep in mind: only one type of tag can be used at a time; the following is NOT valid: report_[CURRENT_DAY]_something_[CURRENT_HOUR] | Optional |
| outputParameters | outputDestination: String | HDFS/FTP/SFTP/AWS: the type of output of the task (default: HDFS); Note: AWS cannot be used yet. | Optional |
| outputParameters | relativeDirectory: String | the sub-directory to be used for FTP/SFTP output - the base directory being the one of the network | Optional |
| outputParameters | s3bucketname: String | the bucket name for AWS S3 output; Note: AWS cannot be used yet. | Optional |
| outputParameters | timezone: String | NET/UTC: the timezone to be used in the output dates; Note: the partner timezone is specific to RTB (default: NET) | Optional |
| SamplingRate | Double | the sampling rate for the requested logs (example: '50' will extract 1 out of 50 logs) | Optional |
| scheduling | jobperiodicity: String | the frequency of the scheduled task to launch (HOURLY, DAILY, WEEKLY, MONTHLY) | Optional |
| scheduling | schedulingEndDate: String | the end date of a scheduled task (limited to 6 months) | Optional |
| scheduling | schedulingStartDate: String | the launch date of the first scheduled task | Optional |
| Startdate | Date / RelativeDate | the start date of the extract, format: |