SmartHub Userguide

Introduction

SmartHub is the platform that allows you to connect with multiple SSP and DSP platforms to facilitate the trading of media advertising inventory.

After your user account has been created, check your email to proceed with registration and login to the platform.

Glossary

Below provided descriptions of key terms and abbreviations used in the system.

  • Bid – the basic unit of interaction between a publisher, ad exchange and an advertiser.
    This is a package with information about an ad placement (bid request) and advertising information (bid response).
  • Bid Floor – a minimal price for the thousand impressions. Bids with the lower price will be ignored.
  • CPM – cost per mille (the price to pay for one thousand impressions).
  • Endpoint – physical point (IP address) that connects platforms to the exchange.
  • Impression – a moment when the ad is shown to the user (loaded on a webpage/app).
    Note: payments are calculated by this parameter.
  • Mismatch – a case when IP or application bundle in the request and IP or application bundle on corresponding impression are different.
  • Nurl – win notification URL (a link by which the exchange notifies the advertiser about the win of its ad).
  • QPS – a number of queries (bids) sent from/to the exchange system per second. Basically used to specify potential amount of queries that the system is capable to handle.
  • Pop traffic – the advertising through a new pop-up window or a new tab in the current window. It is fullscreen advertising, with no size.
  • Push traffic – traffic through the push notifications.
  • Request – an HTTP packet sent from the publisher to the exchange containing information about placement.
  • Response – an HTTP packet sent from the exchange to the publisher containing information about the creative to display.
  • Spend – the amount of money ($) spent to purchase the traffic.
  • Spend Limit – maximal amount of money ($) that can be spent.
  • Timeout – amount of time that the publisher/exchange can wait for bid response.
  • Win – an event when the creative wins the RTB auction and is going to be shown to the user.
  • WinRate – wins to bids ratio.

Interface

Looking through the system sections, you can use the different interface tools to get exactly the information you need, to optimize the display of data, and make your work easy.

Apply filters

Use the filters to see only information that you need at the time.

The filter pane is located at the top of the section page and can be used to filter data by different fields depending on the section.

To apply filters, select needed values in the fields and click ‘Generate’.

 

For example, in the Statistics section you can filter using these filters:

  • Date – here you can select the period to accumulate the data. Available date ranges: today, yesterday, this week, last week, last month, month-to-date, or custom date range.
  • DSP Company or Endpoint – here you can select ‘All’ DSPs or Endpoints, or one specific DSP or its Endpoint.
  • SSP Company or Endpoint – here you can select ‘All’ SSPs or Endpoints, or one specific SSP or its Endpoint.
  • Filter By – you can select the field by which you can filter. For example, select field Resource, where you can filter by domain/bundle.

There may be other filters in the other sections, such as:

  • Search field in the main section. Such field allows you to type the part of the SSP/DSP/Endpoint name to find SSPs/DSPs/Endpoints that contains that text in its name.
  • Group By field in the DSP/SSP Statistics field. It allows group information by hours or by days. If grouped by hours, you will see the information by each hour of the day.

Select columns to display

While watching statistics, you can change the data to display and see only the data you need.

To do so, click on button and in the dropdown list appeared, tick off the fields you want to see:

 

Sort the data in the table

You can sort the data by one value (column) to see at the top of the table the companies (endpoints,etc.) which have the highest / lowest value.

Click on the column name to sort the data in the table. The data will be sorted descending (from higher value at the top to lower at the bottom, as indicated by such icon: ). To make ascending sorting (icon ), click on the column name again.

For example, you can sort by ‘Impressions’ column to see the companies that received the most impressions at the top of the table, or you can sort by the ‘Date’ column to see the dynamic of impressions by days.

Note: you can make sort descending or ascending.

 

Expand/collapse the demand or supply side info

As the Main section displays two different types of entities, the SSPs and DSPs companies and endpoints, its screen divided into two halves.

You can collapse one of that halves to see more info about the type of entities you need at the moment.

 

Sections overview

The platform consists of the following sections:

 

Main – endpoints of supply and demand sides.

Statistics – detailed statistics about impressions – SSP, DSP, domain/bundle, creative ID, publisher ID, etc.

DSP/SSP Statistics – quantity of bid requests and responses, errors and timeouts.

Req/Res Statistics – detailed info about requests and responses you receive and send.

Billing – payments information.

Companies – partners (SSPs and DSPs) you are working with.

Main

Here you can manage the endpoints of companies.

The screen is divided into two parts: SSP endpoints are on the left side and DSP endpoints are on the right side. You can expand one side by clicking the button. To see the hidden side, click on its label on the right side of the screen:

 

On both sides you can see the lists of the endpoints grouped by companies:

 

Initially, each list displays companies. To expand the list of endpoints of a particular company, click the symbol.

 

To edit an existing endpoint or to see its statistics, hover over the right side of the endpoint record:

 

Supply Side endpoints

Click on the button to select the columns to display:

By default, you will see all available columns:

  • OFF/ON – status of the endpoint. Contains the switcher that turns endpoint on or off. If the endpoint is active, the switch is colored green. This field cannot be hidden.
  • ID – unique identifier of a record.
  • Name – endpoint name. This field cannot be hidden.
  • Type – endpoint type: RTB endpoint or VAST.
  • Region – data center location.
  • QPS – real time number of requests (queries per second) that you are receiving from the SSP.
  • Bid QPS – real time number of responses (queries per second) that you are sending to the SSP.
  • Daily Spend – daily spend (in $) on this endpoint (in UTC time zone).
  • Scanner – list of scanners, active for the endpoint.
  • Default Timeout – default ‘tmax’ value. This setting is applying by the system only in case your SSP does not send field ‘tmax’ in its requests.
  • Default Bid Floor – default bid floor value. This value is applying in two cases: 1) bid floor is absent in SSP’s requests, 2) bid floor in SSP’s requests is lower than the default bid floor. 
  • Spend limit – daily spend limit for the endpoint (in US dollars).
  • WinRate – the ratio of your bids to your imps. The value is calculated based on bids and imps quantity for the last 6 hours.
  • Comments – here you can save additional information about the endpoint.

 

 

Click ‘New Endpoint’ to create a new supply side endpoint.

Here you need to do the following:

  • Set the endpoint name.
  • Set the type – RTB Endpoint or VAST.

 

For RTB Endpoint, set such parameters:

  • Select a company that owns the endpoint.
  • Select the region of the data center.
    Note: you cannot change the region later.
  • Set the margin for the endpoint (we recommend you not to set margin higher than 15%).
  • Set the spend limit for the endpoint (optional).
  • Add a comment if you have additional information about the endpoint.
  • Tick off ‘Pop traffic’ and/or ‘Push’ if you want to allow requests for those traffic types.
  • Tick off ‘Send XML Responses (for Pop traffic only)’ if needed. In this case the response will be wrapped in XML.
    Contact technical specialists on the SSP side to find out if that option needed.

 

For VAST Endpoint, set the following parameters:

  • Bidfloor – all the requests will have this bidfloor.
  • Sizes – ‘All Sizes’ in case the SSP serves different sizes. Or, select ‘Custom Sizes’ and set Width and Height – in this case, SmartHub will set that size for all requests.
  • Company to which the endpoint belongs.
  • Region in which the endpoint’s servers are located.
  • Margin
  • Spend Limit
  • Set whether to use or not to use a Protected Media scanner (if must be enabled on the SSP side).

 

Set the ‘Platform Statistics API link’ that you received from your SSP. This is the link that allows you to receive statistics from the SSP side.

WARNING: you must change dates in the link to [%Y-m-d%] symbols.

After you have specified the statistic API link, click 'Test' to verify it. You  will receive ‘code 200’ notification in case of success.

 

Once you have finished the setup, click ‘Save’.

Endpoint link and ‘SSP’s Statistic API link’ will be created automatically. Provide the SSP with the ‘SSP’s Statistic API link’ to allow SSP to receive statistical information from Smarthub.

You can open the endpoint edit page and copy that links:

 

Also, you can configure additional settings for saved endpoint:

Settings for RTB Endpoint:

  • Default tmax – set the ‘tmax’ value to apply in case the SSP does not send field ‘tmax’ in its requests.
  • Default Bidfloor – bidfloor value to apply in case the bidfloor field not present in the request.
  • Filters:

     

    • Set allowed or blocked DSPs.
    • Set Blocked crids (creative ids) – add creative ids that must be blocked for this SSP.
    • Set ads.txt – here you can specify sellers that are authorized to work with this SSP.

Also, you can get examples of requests and responses. Click ‘Valid Response Sample’ or ‘Example Response’ to see the randomly selected examples of requests or responses:


 

Settings for VAST endpoint:

  • Set allowed or blocked DSPs.
    To set the list of blocked creative IDs, click ‘Blocked crids’ on the edit page of an existing endpoint, then add the list manually (put each ID in a new line) or upload a TXT file with the list of crids:

    You can also download the list to your device.
  • Set Blocked crids (creative ids) – add creative ids that must be blocked for this SSP.
  • Set ads.txt – here you can specify sellers that are authorized to work with this SSP.

Demand Side endpoints

Click the button to select the columns to display:

By default, you will see all available columns:

  • OFF/ON – status of the endpoint. This field cannot be hidden.
  • Name – endpoint name. This field cannot be hidden.
  • Region – region of the data center.
  • Banner – indicates whether banner traffic is allowed for the endpoint.
  • Native – indicates whether native traffic is allowed for the endpoint.
  • Video – indicates whether video traffic is allowed for the endpoint.
  • Nurl – this setting indicates if you will call Nurls (win notifications) of DSPs.
  • Limit QPS – max QPS allowed for the endpoint. Please do not leave this field empty.
  • Daily Spend – actual daily spend on the endpoint (in US dollars).
  • Spend Limit – daily spend limit of the endpoint (in US dollars).
  • Real QPS – real time number of requests (queries per second) received by specific DSP from all linked SSPs.
  • Bid QPS – real time number of bids (queries per second) received from the DSP.
  • Email – contact email.
  • Comments – additional information about the endpoint.

 

 

Click ‘New Endpoint’ to create a new endpoint for the DSP.

Here’s what you need to do here:

  • Set the endpoint name, select company.
  • Select the region of the data center.
    Note: you cannot change the region later.
  • Set the margin for the endpoint. We usually recommend to set margin 0% for DSPs, and increase it only for those DSPs that bid with high prices.
  • Set the Spend Limit for the endpoint (optional).
  • Set QPS Limit – maximum QPS allowed for the endpoint. Please do not leave this field empty.
  • Endpoint – the endpoint link you have received from your DSP.
  • Select allowed Ad Types (Mob, InApp, Desktop).
  • Select allowed Ad Formats (Banner, Native, Video, Only Rewarder Video, Pop, Push).
  • Set Filters:

     

    • Only with User ID – select this setting if the DSP requires IFA.
    • Mismatched IP Filter –  if you turn this filter on, the system will filter out all sources on which a high percentage of IP mismatches is observed. By IP mismatches, we mean cases when IP in the request and IP on which the impression happens are different. 
    • Mismatched Bundle Filter – this filter does the same as Mismatched IP filter but tracks mismatches of bundles.
    • Filter out CTV (dev.types 3, 6, 7) – set if the endpoint is not allowing Connected TV traffic.

 

Secure Filter – select if DSP will receive secure or non-secure traffic, or both.

Porn Filter – select ‘All’ if the DSP can receive any traffic including the adult traffic, select ‘Exclude Adult’ if the adult traffic is not allowed, or select ‘Only Adult’ if the DSP is interested to receive only adult traffic.

Note: Such traffic is identified by the system by the keywords in domain names.

 

Set the ‘DSP Statistics API link’ that you received from the DSP. This is the link that allows you to receive statistics from the DSP side.

WARNING: you must change dates in the link to [%Y-m-d%] symbols.

After you have specified the statistic API link, click 'Test' to verify it. You  will receive ‘code 200’ notification in case of success.

 

After finished, click ‘Save’.

 

Once you saved the endpoint, you can return to edit it, and see some additional settings:

 

Min tmax – set minimal tmax that you will be sending in requests to the DSP. Requests with lower tmax value will not be sent.

Note: Use this option to specify with DSPs that can not read the timeout from the bid request.

Max Bidfloor – set the maximal bidfloor you will send to this DSP.

 

Allowed Countries – set the list of countries from which the traffic is allowed.

Allowed Sizes – set the allowed sizes.

Select allowed or blocked SSPs if needed.
Note: you can select blocked or allowed SSPs only if the Country is selected.

Set the list of allowed Connection Types if needed.

 

Note: Smarthub has in-built throttling system, which means that you will mostly send to your DSPs traffic to which they bid. For instance, if your DSP bids only to USA, you will send mostly USA traffic, and few requests from other geos.
The throttling system takes into consideration the following fields: traffic format, traffic type, domain/bundle, country, size, connection type, OS, and whether traffic is secure or non-secure, interstitial or not. Therefore, unless your DSP requires strict targeting (by geos, sizes, OS, etc), we do not recommend to set such targeting. 

 

You can also set lists of allowed or blocked bundles, sites, and publishers:

Click ‘Bundle’, ‘Sites’, or ‘Publishers’ link to set the list. In a form opened, you can edit the list, or download it as a file, or upload it from file.

The system provides statistical info of the endpoint via ‘DSP Statistic API link’. Provide your DSP with this link to allow receiving statistics from Smarthub.

Click ‘Valid Response Sample’ or ‘Valid Request Sample’ to see the randomly selected examples of responses and requests.

Set Contact Email and Comment, if needed.

Statistics

This tab contains information about impressions. Info is updated with a couple of hours delay.

After opening the section, set the configuration you need:

Select particular Company or Endpoint, or select ‘All’ to see the statistics for all endpoints.

Select the range of Dates: Today, Yesterday, This Week, Last Week, Last Month, MTD (Month-to-date), or Custom (in this case, set the date range manually).

Set the parameter to Filter by, if needed: DSP/SSP Endpoint, Resource, Creative, Publisher. Then, type the part of parameter value (for example, type ‘domain12’ to find ‘domain123.com’ and ‘domain11.net’).

Use button to select fields to display and to group data by them. For example, you can hide the Domain/Bundle field, so data will not be grouped by different domains/bundles.

Click ‘Generate’ to generate/update the statistics page.

The table has the following fields:

  • Date
  • DSP (SSP) Company
  • DSP (SSP) Endpoint
  • Domain/Bundle
  • Publisher
  • Creative
  • App/Site
  • Country
  • Traffic type
  • Width
  • Height
  • DSP Spend, $
  • SSP Spend, $
  • Impressions
  • DSP CPM – the cost for a thousand impressions that DSP pays
  • SSP CPM – the cost per thousand impressions that SSP earns.

 

You can export the statistics by clicking the ‘Export’ button in the upper right corner. The Excel file will be downloaded to your device.

DSP/SSP Statistics

Here you can see detailed information about bid requests and responses (valid and invalid) for particular DSPs and SSPs. Info is updated with a couple of hours delay.

After opening the section, set the configuration you need:

Select the Type of endpoint, DSP or SSP.

Select the range of Dates: Today, Yesterday, This Week, Last Week, Last Month, MTD (Month-to-date), or Custom (in this case, set the date range manually).

Select Timezone.

Select particular endpoint in the DSP Endpoint filter (or SSP Endpoint filter) field, if you want to see information only for this endpoint.

Click ‘Generate’.

DSP Statistic


The table has the following fields:

  • Date
  • Company
  • Bid Requests sent to DSP
  • All Bid Responses (valid and invalid)
  • Valid Responses
  • Timeouts – the number of requests that exceeded time limit (with a ratio to the total number of requests). If the Timeouts value is more than 10%, refer to the specifications or contact us.
  • Server Connection Errors – connection errors, such as lost connection with DSP.
  • Other Responses – the number of responses that declined for some of the following reasons: 

     

    • No ‘price’ or ‘adm’ in the response 
    • Invalid price in response (for example, price in response is lower than bidfloor in the request)
    • Incorrect currency in the response
    • Domain in response is in the blocklist (blocked by scanner)
  • Impressions – a number of impressions received.

SSP Statistic

 

In the SSP Statistics table, you can see the following fields:

  • Date
  • Company – the name of the company.
  • Endpoint – the name of the endpoint.
  • Bid Requests from SSP – total number of requests received from SSP.
  • Bid Requests sent to DSP – a number of requests that is valid and sent to DSP.
  • Invalid Requests – the quantity of invalid requests by reasons.
    Possible reasons:

     

    • Invalid Tmax - as the SmartHub works only with tmax=60ms or bigger, requests with tmax less than 60ms falls into invalid requests.
    • Invalid device object - either we could not parse the user agent, or there are no data on the ip address from the request in MaxMind.
    • Min requirements fail - lack of fields in the request that are required by our specification, such as id, device object with IP and user-agent fields, imp object with traffic type (banner, video or native), width and height or format object, site or app object with domain/page or bundle fields).
    • global_black_list - A request came from a resource that is in the global black list (created by the partner in the account settings)
    • parse_request_fail - invalid JSON in the request
    • total_spend_limit - The purchase limit for this SSP has been reached (set by the partner in the settings of each SSP)
    • No valid DSP - there are no DSP for the received type of traffic, or bid request haven't passed the filters and targeting settings on the DSP side.
      For example, there is a request for a native ad, but there is no active DSP that buys native traffic. Or, the requests are filtered due to the following settings on the DSP side: mismatches, block/allowed lists, tmax/bidfloors setting, secure settings, 'Exclude adult' options and so on.
  • Impressions – total number of impressions received.

 

Req/Res Statistics

Here you can see the statistics of requests and responses.

The table contains the following fields:

  • Date
  • DSP endpoint
  • SSP company
  • SSP endpoint
  • DSP company
  • Domain/bundle
  • Invalid requests
  • SSP requests to DSP
  • DSP responses (total)
  • DSP responses (valid)
  • Impressions
  • Win rate

To filter records by date, or some DSPs or SSPs, or bundles, select the required field from drop-down list and click ‘Generate’ to apply the filter.

Billing

This tab shows total amounts of imps and spend for SSPs and DSPs.

Having opened the section, set the configuration you need:

Set the Type of endpoint (SSP or DSP).

Select particular Company, or select ‘All’ to see the statistics for all companies.

Select the Period: Today, Yesterday, This Week, Last Week, Last Month, MTD (Month-to-date), or Custom (in this case, set the date range manually).

Then click ‘Filter’ to get the required data:

 

 

You will see the following data:

  • Company – company name.
  • Endpoint – endpoint name.
  • Imps – the number of impressions.
  • Cost – the cost figures earned/paid for impressions.
  • Imps API link – the number of impressions received via API link. You can edit the numbers. To do so, click 'pencil' icon.
  • Imps Discrepancy – discrepancy between impressions figures on platform and that received via API link. You can recalculate discrepancy percentage by clicking 'refresh' icon.
  • Cost API link – the cost figures received via API link. You can edit the numbers. To do so, click 'pencil' icon.
  • Cost Discrepancy – discrepancy between cost figures on platform and that received via API link. You can recalculate discrepancy percentage by clicking 'refresh' icon.
  • Terms – deferment of payment

 

By default, you see the list of endpoints. Click ‘Endpoints / Companies’ to switch to ‘companies’ view, where you can see endpoints grouped by companies.

To expand the list of endpoints of the particular company, click the symbol.

 

You can export the statistics by clicking the ‘Export’ button in the upper right corner. The Excel file will be downloaded to your device.

 

Companies

Here you can see your companies, their creation dates, contacts, terms and dates of their invoices and payments.

To edit an existing company, click on its name, make changes and click ‘Save’.

 

Click ‘Add company’ to create a new one:

Set the company name, its domain, main contact, and email.

Set the terms:

Terms – deferment of payment (NET30, NET15, etc).

Start Date – the date when the company is about to start trading.

Invoice Date – the date to send/receive the first invoice.

Management sections

Hover a mouse over the user icon in the upper right corner to open additional sections such as Settings, User Management, Global Blacklist, Mismatches.

Settings

This section consists of four areas: UUID and ads.txt settings, Sellers.json settings, CRIDs edit settings, Scanners settings: TMT Settings, Forensiq and Protected Media settings.

General settings allow you:

  • get ID (UUID) to receive access to statistics via API (please reach out to your AM if you need API documentation).
  • set ads.txt Tag ID issued by certification authority.
  • set CRIDs edit settings: you can add your company name before the actual crid.

 

Scanners settings allow set up TMT, Forensiq and Protected Media scanners. allow configuring traffic/demand scanners.

To activate ad tags scanning, specify authorization and scanning parameters.

TMT

  • API key – TMT access key.
  • Personal API EP – API endpoint link.
  • Scans daily limit – overall maximum number of scans that TMT will perform each day.
  • One tag scans limit – number of scans for one tag (per day).
  • Remove tag period (hours) – number of hours after which the tag will be deleted from TMT database.

You can download Crid report and Domain report to see blocked tags statistic.

 

Forensiq

  • Client ID – tag ‘Org ID’
  • Client Key, Client Secret – authentication parameters for your Forensiq account
  • Username, Password – authentication parameters for API
  • Scan Limit – overall number of scans per day.

 

Protected Media

  • PM account id – Protected Media account identifier
  • Project ID, Private Key ID, Private Key, Client Email, Client ID – authentication data. You will receive values for these fields after registration.

 

After settings done, you can activate Protected Media scan for each endpoint. To do so, go to the Main section, open an endpoint settings from the list of endpoints and tick off the ‘Scan with Protected media’ checkbox.

 

You can download a report to see the blocked publishers.

User Management

You can create new users or see existing users in the User Management section:

 

Here you can see the list of users, with their Names, Emails, Companies, Permissions (Edit, or View, or View Statistics), and their Last Login date:

 

To create a new user, click the ‘New User’ button and specify the user’s first and last name, contact email, and permission level:

 

Users have the following access level permissions:

  • View Statistics allows the user only to see statistics of the user’s company, without access to anything else. This is the permission level that you can give to your external partners – SSPs and DSPs.
  • View allows the user only to view records.
  • Edit allows the user to edit records.

Click ‘Send Access’ to confirm user creation. The user will receive an email to set a password and get access to the platform.

Global Blacklist

Here you can block website domains, applications, and bundles.

On the page, you see the list of blocked items:

To remove item from the list and unblock it, click symbol beside the corresponding item.

To add a new sources, click ‘Add Items’, and in the window opened, type each item from a new line and click “Save’:

You can add new blocked items by uploading them from CSV or TXT file. To do so, just click icon, click ‘Upload File’, select a file and click ‘Save’:

 

Also, you can download the entire list of blocked items. Just click icon and the list will be downloaded as CSV file.

 

Mismatches

This section contains archives of mismatches for the previous day – IP mismatches and Bundles mismatches. If you do not turn these filters on at least for one DSP, there will be no data in this section.

Note: Data on mismatches are stored only for one day.

Suggest feature

If you feel the need in some function and want to propose an improvement, use the ‘Suggest feature’ form:

 

Just describe your idea, add a screenshot if needed, and send your suggestion. Our team will review it, and maybe you’ll see the new functional soon!