Implementing Overwolf Ads: Tips & Tricks
Ads in Overwolf are a great and effective monetization tool but, at some level, when your app gets complex and with lots of windows, it can get tricky to manage Ads properly.
This article is a nice place to start, seen all at once all these steps can be difficult to remember and sometimes to implement.
The goal is to create placements that are attractive to advertisers based on the Overwolf policy guidelines and maximize advertisers KPIs such as completion rate & Viewability.
Below is the schema of all things you should consider while implementing Ads in your app:
And now, let’s go over each logical block of controls to be performed.
The Ads container
Usually, in an app composed of multiple windows, you should tend not to replicate the same code, helped by frameworks like React, Vue, or Angular, you can create components that contain logic, HTML, and calls to the Overwolf SDK.
This can be a starting point: https://github.com/overwolf/community-gists/blob/master/common-services/ads-service.js .
A simple approach to centralize the management logic of your Ad component.
Ad Component contained in the Top Level Component
The documentation says: “Ads box is not refreshed when navigating components inside the same window.”
This is the key to ensuring high performance for the ads in your app.
But exactly what does that mean? Translating this description using frameworks like React or Vue — meaning that the Window component must directly contain the Ad component. The Router must be at the same level as the Ad component.
In this way, the Ad component is never unmounted from the DOM and remains always alive and present despite navigating to subcomponents or routes of the same window.
The hierarchy should be:
<Window>
<Router>
<Component1 />
<Component2 />
</Router>
<AdContainer />
</Window>Absolute positioning
The documentation says that the Ads container must always be in the same place, preserving the User Experience, so your window must be built to make sure you keep the place for the ads in every situation.
The most common thing is to allocate a column, left or right, so you can be sure that the rest of the content doesn’t go on top of the ads space.
It is a good rule to keep the ads container with an absolute position via CSS.
Be sure the container is not scrollable as well.
position: absolute;
right: 10px;
bottom: 10px;
width: 400px;
z-index: 999999;Minimum Window size
One of the tests that Overwolf QA does, is to resize the window to make sure that the Ads, due to their absolute positioning, don’t go on top of the rest of the content or get hidden.
To avoid this, set the minimum window size in the manifest.json.
Minimize and restore the window
One of the common actions is to minimize and restore the window: the action of minimizing the window must disable the Ads, the restore must reactivate them.
To control correctly this behavior, overwolf.windows.onStateChanged helps us, but the snippet reported in the documentation is not correct: this event is triggered for all windows, not only for the current one, the developer must check if the event is triggered for the current window.
overwolf.windows.onStateChanged.removeListener(this.onWindowStateChanged.bind(this)); overwolf.windows.onStateChanged.addListener(this.onWindowStateChanged.bind(this));onWindowStateChanged(state) {overwolf.windows.getCurrentWindow(result => {
if (state && result.status == "success" && result.window.name == state.window_name && this.owAd != null) {// when state changes to minimized, call removeAd()
if (state.window_state === "minimized") {
this.owAd.removeAd();
}
// when state changes from minimized to normal, call refreshAd()
else if (state.window_previous_state === "minimized" && state.window_state === "normal") {
this.owAd.refreshAd();
}
}
});
}
Checking result.window.name == state.window_name ensure you are managing the Ads for the current window change and not for all windows state change.
Manage Window visibility
During usage the window could be hidden behind other windows or even behind the game if in full screen.
overwolf.windows.isWindowVisibleToUser allows to control if the window is totally or partially visible to the user.
In case it is hidden, you have to disable the ads, once it becomes visible again, reactivate them.
Unfortunately, there is no event handler for this function, so it is necessary to control its visibility with a timer (setInterval).
The recommended approach is to use a boolean that is updated when the visibility changes.
Manage the focus Game change
This mechanism applies to in-game windows.
When the window is open and the game is minimized (with Win+D or ALT+TAB), you have to deactivate the ads, when the game comes back in focus, reactivate them.
overwolf.games.onGameInfoUpdated signals when the game changes focus.
To better control this behavior, your Ad component must know that it is inside an in-game window.
Manage Windows Priority
This is a rather advanced topic and depends heavily on how your app is built and which and how many windows can be open at once.
Overwolf doesn’t want ads to be shown from two windows at the same time: having two ads displayed at the same time is not only bad UX but also dangerous for revenue because it increases the risk of fraud and puts two publishers in competition.
If your app can have two windows containing ads open at the same time, for example, an in-game window and a desktop window positioned on the second screen — therefore always visible even with the game in focus — you must pay close attention to the “Priority” of the windows.
It is recommended to keep an array of windows containing ads ordered by priority and at each change of state of the windows using overwolf.windows.onStateChanged, check if the window that has changed state is priority over the current window and consequently, hide the ads in the less important window.
Wrapping up
Developing your app with frameworks like Vue or React, you can make extensive use of “reactive properties” using watchers, in Vue, or hooks in React.
These techniques help a lot in controlling booleans that tell you what to do in each situation, variables that change automatically based on the above.
In the end, your code will probably have several control booleans because you’ll have to take into account so many different situations.
