# Introduction
Source: https://docs.rev.iq/introduction
Welcome to the RevIQ docs!
## Quickstart
There are a few things you need to do to get started with RevIQ.
Approve our demand for your site
Add our script to your site
Integrate our SDK into your app
# Adblock API
Source: https://docs.rev.iq/js/adblock-api
Roughly 40% of web users use adblock, which can significantly reduce ad revenue.
We offer an **Adblock API** which enables you to prompt adblock users to support
the site.
This API is available as a separate module that you can add to your site by
including an additional script tag. We designed this module to be fast and
lightweight, with a gzipped size of **under 0.3 kB** and requiring no external
dependencies.
## Enable Wrapper Adblock API
Add the Adblock API Module code to the \
section of your webpage. We put an `id` so you can remember what
it's for :)
```html theme={null}
```
## Using the Adblock API
Note: You should **NOT** use the command queue (`reviq.push(cmd)`) for
these functions. These functions are always available immediately after the
Adblock API Module is loaded.
Suppose you have some function `showAdblockModal` that shows a modal asking
users to disable adblock.
`reviq.onAdblock(cb)`: runs a callback `cb` if adblock is detected
```js theme={null}
reviq.onAdblock(() => {
// This only runs if adblock is detected
showAdblockModal();
});
```
`checkAdblock()`: must be awaited and returns true if adblock is detected, false otherwise
```js theme={null}
// Check for adblock
const hasAdblock = await reviq.checkAdblock();
if (hasAdblock) {
showAdblockModal();
}
```
# consent.ready
Source: https://docs.rev.iq/js/consent.ready
Check if the user consent data is ready.
```js Show consent dialog theme={null}
// Resolves after:
// - No consent jurisdiction (gdprApplies = false)
// - User sets consent preferences (approve or reject, gdprApplies = true)
const tcData = await reviq.consent.ready();
const gdprApplies = tcData.gdprApplies;
if (!gdprApplies) {
// GDPR does not apply.
return;
}
const accessDeviceStorage = tcData.purpose.consents[1];
const selectBasicAds = tcData.purpose.consents[2];
const createAdsProfile = tcData.purpose.consents[3];
const selectPersonalizedAds = tcData.purpose.consents[4];
const createContentProfile = tcData.purpose.consents[5];
const selectPersonalizedContent = tcData.purpose.consents[6];
const measureAdPerformance = tcData.purpose.consents[7];
const measureContentPerformance = tcData.purpose.consents[8];
const understandAudiences = tcData.purpose.consents[9];
const developAndImproveServices = tcData.purpose.consents[10];
const selectBasicContent = tcData.purpose.consents[11];
```
## `tcData.purpose.consents`
```md theme={null}
## Purpose 1. Store and/or access information on a device
Cookies, device or similar online identifiers (e.g. login-based identifiers,
randomly assigned identifiers, network based identifiers) together with
other information (e.g. browser type and information, language, screen
size, supported technologies etc.) can be stored or read on your device to
recognise it each time it connects to an app or to a website, for one or
several of the purposes presented here.
## Purpose 2. Use limited data to select advertising
Advertising presented to you on this service can be based on limited
data, such as the website or app you are using, your non-precise
location, your device type or which content you are (or have been)
interacting with (for example, to limit the number of times an ad is
presented to you).
## Purpose 3. Create profiles for personalised advertising
Information about your activity on this service (such as forms you
submit, content you look at) can be stored and combined with other
information about you (for example, information from your previous
activity on this service and other websites or apps) or similar users.
This is then used to build or improve a profile about you (that might
include possible interests and personal aspects). Your profile can be
used (also later) to present advertising that appears more relevant
based on your possible interests by this and other entities.
## Purpose 4. Use profiles to select personalised advertising
Advertising presented to you on this service can be based on your
advertising profiles, which can reflect your activity on this service
or other websites or apps (like the forms you submit, content you look
at), possible interests and personal aspects.
## Purpose 5. Create profiles to personalise content
Information about your activity on this service (for instance, forms
you submit, non-advertising content you look at) can be stored and
combined with other information about you (such as your previous
activity on this service or other websites or apps) or similar users.
This is then used to build or improve a profile about you (which might
for example include possible interests and personal aspects). Your
profile can be used (also later) to present content that appears more
relevant based on your possible interests, such as by adapting the
order in which content is shown to you, so that it is even easier for
you to find content that matches your interests.
## Purpose 6. Use profiles to select personalised content
Content presented to you on this service can be based on your content
personalisation profiles, which can reflect your activity on this or
other services (for instance, the forms you submit, content you look
at), possible interests and personal aspects. This can for example be
used to adapt the order in which content is shown to you, so that it is
even easier for you to find (non-advertising) content that matches your
interests.
## Purpose 7. Measure advertising performance
Information regarding which advertising is presented to you and how you
interact with it can be used to determine how well an advert has worked
for you or other users and whether the goals of the advertising were
reached. For instance, whether you saw an ad, whether you clicked on
it, whether it led you to buy a product or visit a website, etc. This
is very helpful to understand the relevance of advertising campaigns.
## Purpose 8. Measure content performance
Information regarding which content is presented to you and how you
interact with it can be used to determine whether the (non-advertising)
content e.g. reached its intended audience and matched your interests.
For instance, whether you read an article, watch a video, listen to a
podcast or look at a product description, how long you spent on this
service and the web pages you visit etc. This is very helpful to
understand the relevance of (non-advertising) content that is shown to
you.
## Purpose 9. Understand audiences through statistics or
## combinations of data from different sources
Reports can be generated based on the combination of data sets (like
user profiles, statistics, market research, analytics data) regarding
your interactions and those of other users with advertising or
(non-advertising) content to identify common characteristics (for
instance, to determine which target audiences are more receptive to an
ad campaign or to certain contents).
## Purpose 10. Develop and improve services
Information about your activity on this service, such as your
interaction with ads or content, can be very helpful to improve
products and services and to build new products and services based on
user interactions, the type of audience, etc. This specific purpose
does not include the development or improvement of user profiles and
identifiers.
## Purpose 11. Use limited data to select content
Content presented to you on this service can be based on limited data,
such as the website or app you are using, your non-precise location,
your device type, or which content you are (or have been) interacting
with (for example, to limit the number of times a video or an article
is presented to you).
```
# consent.show
Source: https://docs.rev.iq/js/consent.show
Show the user consent management dialog.
```js ShowConsentDialog theme={null}
reviq.consent.show();
```
# Using the JavaScript API
Source: https://docs.rev.iq/js/introduction
## Sync API
To ensure that your code runs after the RevIQ script is loaded, you can use the
`reviq` command queue.
The RevIQ script loads asynchronously in order to not block the page. It's
important to make sure that the API is ready before you call it.
```js index.js theme={null}
globalThis.reviq = globalThis.reviq || [];
reviq.push((reviq) => {
// Your code here
reviq.setKv('foo', 'bar');
});
```
Alternatively, you can create a Promise that resolves after the first `reviq`
command is called.
```js index.js theme={null}
const reviqReady = new Promise((resolve) => {
reviq = reviq || [];
reviq.push((reviq) => {
resolve(reviq);
});
});
async function doSetKv() {
const reviq = await reviqReady;
reviq.setKv('foo', 'bar');
}
```
# setAdsEnabled
Source: https://docs.rev.iq/js/setAdsEnabled
Set visibility of ads on the page
This can be useful for paid users, though it is
recommended to omit the RevIQ script entirely on pages where ads are not
desired.
Whether ads should be enabled
```js Disable ads theme={null}
reviq.setAdsEnabled(false);
```
```js Enable ads theme={null}
// Only needed if ads were previously disabled
reviq.setAdsEnabled(true);
```
# setKv
Source: https://docs.rev.iq/js/setKv
Sets a key-value pair for optional targeting
You may not pass any user-identifiable data (including names, addresses, or user
IDs) in targeting.
The targeting key
The targeting value
```js Set a key-value pair theme={null}
reviq.setKv("key", "value");
reviq.setKv("dog", "woof");
reviq.setKv("cat", "meow");
```
```js Set multiple key-value pairs theme={null}
reviq.setKvs({
"key": "value",
"dog": "woof",
"cat": "meow"
});
```
```js Verify key-value pairs theme={null}
googletag.pubads().getTargeting("key"); //= ["value"]
googletag.pubads().getTargeting("foo"); //= ["bar"]
googletag.pubads().getTargeting("cat"); //= ["meow"]
```
# setKvs
The `setKvs` method is a convenience method for setting multiple key-value pairs
at once. It accepts an object where the keys are the targeting keys and the
values are the targeting values.
An object of key-value pairs
# setUid
Source: https://docs.rev.iq/js/setUid
Provide a user ID (uid) for targeting. Variadic.
Providing a UID significantly improves ad performance. As such, it is
optional, but highly recommended.
We comply with all privacy regulations and do not store any user-identifiable
data. Once passed to RevIQ, the UID is normalized and then hashed; we never
store the original value.
If the user has opted out of tracking, the UID will not be stored or
transmitted. Thus it is safe to call this function regardless of the user's
tracking preferences.
```ts theme={null}
type Uid = {
u?: string; // username
e?: string; // email
p?: string; // phone
};
```
```js With email theme={null}
const user = { email: "hachi@rev.iq" };
reviq.setUid({ e: user.email });
```
```js With phone theme={null}
// include country code if possible
const user = { phone: "+1 555-555-5555" };
reviq.setUid({ p: user.phone });
```
```js With username theme={null}
const user = { username: "hachi" };
reviq.setUid({ u: user.username });
```
# Frontend
Source: https://docs.rev.iq/quickstart/frontend
Learn how to add our script to your site
This guide will use self closing tags (`` instead of
``) for simplicity. Most JSX and other modern compilers will
accept this syntax. However, **if you are working in raw HTML, you
should manually close the tags.**
## Add the Rev script
Learn how to add our script to your site.
Add the following script to the `` of your HTML file.
```jsx page.html theme={null}
```
Add the following code
```javascript index.js theme={null}
const script = document.createElement('script');
script.src = '//js.rev.iq/your-domain.com';
document.head.appendChild(script);
```
You may also consider adding the `defer` attribute to the script tag to
optimize initial page load speed.
If wanting to test with another monetization provider per client, you can use
the following code to conditionally load the Rev script.
```javascript index.js theme={null}
const REV_RATE = 0.1; // 10% of users will see the Rev script
const shouldUseRevIq = Math.random() < REV_RATE;
const script = document.createElement('script');
if (shouldUseRevIq) {
script.src = '//js.rev.iq/your-domain.com';
} else {
// Load your other monetization provider
// Set the attributes based on the other vendor's documentation
}
document.head.appendChild(script);
```
## Development
Add the `dev` attribute to the script to use dev placements.
Add the following script to the `` of your HTML file.
```jsx page.html theme={null}
```
Add the following code
```javascript index.js theme={null}
const script = document.createElement('script');
script.src = '//js.rev.iq/your-domain.com';
script.setAttribute("dev", "")
document.head.appendChild(script);
```
## Defining ad units
Add the `data-ad` attribute with the name of the placement to mark where you
want ads to appear.
```jsx theme={null}
```
#### `data-ad-size`
You can customize the ad units by adding the `data-size` attribute with the
desired size.
```jsx theme={null}
```
#### `data-kv-{key}`
Additionally, you can add targeting tags to the ad units by adding the `data-kv-{key}`
attribute.
```jsx theme={null}
```
# Desktop Apps
Source: https://docs.rev.iq/quickstart/native
Serve ads in Electron, Tauri, and any other desktop app
RevIQ works in any desktop app that renders its UI with web technology. If
your app shows HTML in a window, you can monetize it with RevIQ.
## Supported frameworks
* **Electron**, with first-class support through the `rev-utils` helper
([see below](#electron))
* **Tauri**
* **NW\.js, CEF, Wails, Neutralino** and other Chromium- or webview-based
frameworks
* **Native apps with an embedded webview**: WebView2 (Windows), WKWebView
(macOS) and WebKitGTK (Linux)
Add the RevIQ script to the page your app loads, the same way you would on a
website. See [Frontend](/quickstart/frontend). Then make sure your app meets the
two desktop requirements below.
## Desktop requirements
1. **Open ad clicks in the user's default browser.** When someone clicks an
ad, open the landing page in their default browser rather than navigating
your app's window. Only open links in response to a real click. Block
navigations and popups the user didn't trigger, and block file downloads
started by ads.
2. **Send a standard browser User Agent.** Many frameworks add their own name,
and your app's name, to the User Agent string (for example `Electron/…` or
`MyApp/…`). Remove those parts so the string looks like a regular browser.
Non-standard User Agents may be flagged as IVT (invalid traffic). \[?]
## Electron
`rev-utils` handles both requirements for you.
### Installation
Install the rev-utils library to augment your Electron setup with full
compatibility for ads. We may occasionally update the package.
```sh theme={null}
npm i -D rev-utils@https://r2.reviq.app/rev-utils-v1.0.3.tgz
```
### Usage
After creating a window with `new BrowserWindow`, pass the window and the
`electron` global into `setupRevUtils`.
```js main.js theme={null}
const { setupRevUtils } = require("rev-utils");
// Note the import of the global electron here!
const electron = require("electron");
// You can destructure your imports from this module object
const { BrowserWindow } = electron;
const myWindow = new BrowserWindow();
setupRevUtils(myWindow, electron);
```
Under the hood, `setupRevUtils` calls two functions on the window
* `setupLinkHandler` to open ads (and block malicious behavior!)
* `setUserAgent`, which removes non-standard portions of the User Agent string
which may trigger IVT (invalid traffic). \[?]
## Tauri
Build a page on your domain with the RevIQ script and your ad slots (see
[Frontend](/quickstart/frontend)), then show it in a child webview that sends a
standard User Agent and opens ad clicks in the user's browser.
```rust src-tauri/src/ads.rs theme={null}
use tauri::webview::{NewWindowResponse, WebviewBuilder};
use tauri::{LogicalPosition, LogicalSize, WebviewUrl, Window};
use tauri_plugin_opener::OpenerExt;
// A standard Chrome User Agent. Ad providers don't recognize Tauri's default.
const ADS_USER_AGENT: &str = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36";
pub fn add_ads_webview(window: &Window) -> tauri::Result<()> {
let url = "https://your-domain.com/app-ads.html".parse().unwrap();
let builder = WebviewBuilder::new("ads", WebviewUrl::External(url))
// Ads render in iframes, so the click script must run in every frame.
.initialization_script_for_all_frames(include_str!("ads-init.js"))
.user_agent(ADS_USER_AGENT)
// Ad clicks go through open_ad_link, never through new windows.
.on_new_window(|_, _| NewWindowResponse::Deny);
window.add_child(
builder,
LogicalPosition::new(0.0, 0.0),
LogicalSize::new(300.0, 250.0),
)?;
Ok(())
}
#[tauri::command]
pub fn open_ad_link(app: tauri::AppHandle, url: String) {
// Only web pages; never file:// or custom schemes.
if url.starts_with("https://") || url.starts_with("http://") {
let _ = app.opener().open_url(url, None::);
}
}
```
`Window::add_child` is behind Tauri's `unstable` feature. Enable it on `tauri`
in `src-tauri/Cargo.toml`: `tauri = { version = "2", features = ["unstable"] }`.
The webview runs this script in every frame. Ads render inside iframes, so each
frame reports clicks and passes links up to your page, which opens them only
right after a real click.
```js src-tauri/src/ads-init.js theme={null}
// Runs in every frame of the ads webview.
const AD_PAGE_ORIGIN = "https://your-domain.com";
// How long after a click an ad may open its landing page.
const CLICK_WINDOW_MS = 1000;
// Your page (the top frame) opens a landing page only right after a real click.
if (window.top === window) {
let lastClick = -Infinity;
window.addEventListener("message", (event) => {
if (event.data?.adClick) lastClick = performance.now();
if (
event.data?.adOpenUrl &&
performance.now() - lastClick < CLICK_WINDOW_MS
) {
lastClick = -Infinity;
window.__TAURI_INTERNALS__?.invoke("open_ad_link", {
url: event.data.adOpenUrl,
});
}
});
}
// Every frame, ad iframes included, reports clicks and hands links to the
// top frame instead of navigating.
document.addEventListener(
"click",
(event) => {
window.top.postMessage({ adClick: true }, AD_PAGE_ORIGIN);
const link = event.target.closest?.("a");
if (link?.href) {
event.preventDefault();
window.top.postMessage({ adOpenUrl: link.href }, AD_PAGE_ORIGIN);
}
},
true,
);
window.open = (url) => {
if (url) window.top.postMessage({ adOpenUrl: String(url) }, AD_PAGE_ORIGIN);
return null;
};
```
Register the opener plugin and the command:
```rust src-tauri/src/main.rs theme={null}
tauri::Builder::default()
.plugin(tauri_plugin_opener::init())
.invoke_handler(tauri::generate_handler![ads::open_ad_link])
```
Because the ad page is loaded from your domain (remote content), Tauri blocks it from calling commands unless a [capability](https://v2.tauri.app/security/capabilities/) opts that origin in. Grant the `ads` webview only the one command it needs:
```json src-tauri/capabilities/ads.json theme={null}
{
"$schema": "../gen/schemas/remote-schema.json",
"identifier": "ads",
"webviews": ["ads"],
"remote": { "urls": ["https://your-domain.com"] },
"permissions": ["core:default", "allow-open-ad-link"]
}
```
Define that permission for your command:
```toml src-tauri/permissions/open-ad-link.toml theme={null}
[[permission]]
identifier = "allow-open-ad-link"
description = "Allow the ads webview to open an ad's landing page in the browser."
commands.allow = ["open_ad_link"]
```
On Windows, set the ads webview's tracking prevention level to none: call
`ICoreWebView2Profile3::SetPreferredTrackingPreventionLevel` with `COREWEBVIEW2_TRACKING_PREVENTION_LEVEL_NONE` through `with_webview`. WebView2 otherwise blocks the cookies
bidders use to recognize returning users, which lowers bids.
## Other frameworks
Meet the two requirements with your framework's own APIs: set a standard
browser User Agent on the webview, and send link clicks and `window.open` calls
from ad frames to the system browser, only right after a real click. The Tauri
example above shows the full pattern.
Building with a framework not listed here? It will work as long as it renders
web content. Contact your RevIQ account manager if you need help with setup.
# Webmaster
Source: https://docs.rev.iq/quickstart/webmaster
Learn how to approve our demand on your site!
## Updating ads.txt
In order to run RevIQ's demand on your site, you will need to add our sellers to
your ads.txt (Authorized Digital Sellers).
TL;DR - Redirect (301) **your-domain.com/ads.txt** to **rev.iq/your-domain.com/ads.txt**, or
manually add the contents of our hosted file.
### Using redirect
We recommend using a redirect to our ads.txt file. This way, the file can be
automatically updated whenever RevIQ add new demand partners.
If you have existing ads.txt lines, we can add them to the hosted file. Your
RevIQ tech contact (hi ;D) probably imported these during your onboarding, but
if your existing ads.txt is not present in the hosted file, please reach out
to us.
Using a 302 (temporary) redirect is recommended, as it allows you to easily
update or remove the redirect in the future.
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and
select your account and domain.
2. Go to **Rules > Redirect Rules**.
3. Under **Single Redirects**, select **Create Redirect Rule**.
4. Enter a descriptive name for the rule in **Rule name**,
Example: `Redirect to RevIQ ads.txt`.
5. Under **When incoming requests match**, define the **Custom filter expression**:
6. Under **Then**, define the URL redirect settings for requests matching the
rule expression:
7. To save and deploy your rule, select **Deploy**. If you are not
ready to deploy your rule, select **Save as Draft**.
Add the following line to your `.htaccess` file:
Redirect 302 /ads.txt
Add the following line to your `nginx.conf` file:
```nginx nginx.conf theme={null}
location = /ads.txt {
return 302 https://rev.iq/your-domain.com/ads.txt;
}
```
### Manual setup
You can also manually add the lines from our hosted file to your own `ads.txt` file.
If you choose to do this manually, keep in mind that you will need to manually update your `ads.txt` file whenever
we add new demand partners.
Copy the lines from the hosted file at [https://rev.iq/your-domain.com/ads.txt](https://rev.iq/your-domain.com/ads.txt)
and add them to your own `ads.txt` file.
1. Go to **Advanced Ads > Settings** in your [WordPress dashboard](https://wordpress.com/home).
2. Scroll down to **ads.txt**, paste the lines from the hosted file at
[https://rev.iq/your-domain.com/ads.txt](https://rev.iq/your-domain.com/ads.txt).
## Verifying ads.txt
To verify your ads.txt is correctly set up, visit
[https://your-domain.com/ads.txt](https://your-domain.com/ads.txt)