Admiral Ad-free Implementation Guide

How to set up your site to have an ad-free experience for subscribers.

Admiral enables publishers to offer digital subscriptions in exchange for a premium website experience. A common experience is ad-free browsing for subscribers. This guide summarizes the steps a publisher can follow to create the ad-free experience on a site.

This implementation will require development effort from the publisher. The scope of this development effort is as follows:

The publisher must have a mechanism to disable ads from loading on the site
The publisher must have a mechanism to read/write a first-party cookie on the site
The publisher must have a mechanism to add custom JavaScript to the site

Getting Started with the Admiral API

💡 Full Admiral API documentation is here: https://docs.getadmiral.com/docs/js-api

You will use the Admiral API to listen for events and render views related to the subscription service. The specific events and views required for use are detailed throughout the remainder of this document.

IMPORTANT: Before starting, install the Admiral tag on your site

The Admiral tag should be installed directly on page in the <head> for every page of the site. This tag should be as close to the top of the <head> as possible, making it one of the first scripts that run on the site. You can download your Admiral tag directly from the install page of your dashboard, or you can email customerlove@getadmiral.com and our team can send the tag directly to you.

How to determine when to enable the ad-free experience

1. Add the measure.detected event to your site.
This event is fired once the Admiral script has determined if a user has an adblocker or not. This event also includes information about whether or not the user has an active subscription to the site. If the subscribed event returns true, this indicates the user has an active subscription to the site.

window.admiral('after','measure.detected',function(user) {
    if (user.subscribed) {
        //Run code for subscribers
    }
})

2. Write a first-party cookie to keep track of the subscriber state.
When subscribed returns true, a first-party cookie should be set that indicates the user has an active subscription. You should check this cookie/value moving forward to determine if a user is eligible for the ad-free experience.

💡 If the subscribed event returns false, you should be either clearing the cookie value or setting it to a different value that indicates the user no longer has an active subscription.

3. Remove ads for subscribed users. Once it has been determined that a user is subscribed, you should invoke the mechanism to remove ads from the publisher site for that user.

How to determine when to disable the ad-free experience

When a user logs out of their subscription or their subscription is cancelled/expires, the publisher needs to make sure those users are seeing ads on subsequent pageviews. Publishers can implement one or more of the following to accomplish this task:

Update first-party cookie every time measure.detected returns a response. If measure.detected returns false for subscribed, the first-party cookie that has been set should either be cleared, or set to a value indicating that the user is no longer eligible for ad-free.
Update first-party cookie when a user logs in or out using the transact.loggedIn or transact.loggedOut events. The transact.loggedOut event is fired when a user logs out of their account. Publishers should either clear or set the value of the first-party cookie to indicate eligibility for the ad-free experience.

window.admiral('after','transact.loggedIn', function() {
//Run code if user logs in
})

window.admiral('after','transact.loggedOut', function() {
// Rode code if a user logs out
})

Allow users to login, subscribe, or manage their account

Publishers will need to implement a button (link) on the site that enables the following.

💡 Button placement is up to the publisher, although most place on or near the primary site navigation.

1. Login to the site. When a user clicks a designated Login button, the publisher needs to call the transact.login view using the Admiral API. This will open a window that the user will use to log into their account. If a user does not have an active subscription they will be shown offers targeted to them. If the user does not match with any offers, they will receive a message stating there are no available offers.

window.admiral('show','transact.login')

2. Purchase a subscription. Publishers who create their own subscription landing pages may want to include links on that page to open specific subscription offers. This can be accomplished by calling the transact.subscribe view using the Admiral API. This view allows you to trigger the subscription popup. By default this view will show offers targeted to that user, but it also accepts offerID as an option if you want to open the subscribe window with a single offer preselected.

window.admiral('show','transact.subscribe',{
    offerID: 'your-offer-id-here'
    //To display multiple offers, you can pass multiple offerIDs separated by a comma
    //offerID: 'your-first-offer-id-here,your-second-offer-id-here'
})

3. Manage a user account. When a user is logged in to their subscription account on a site, publishers need to provide a way for users to manage their account/subscription. To do so, publishers need to call the transact.manage view using the Admiral API. This view opens a new window directly to a user’s account management page. Here they'll be able to manage their subscriptions, edit their payment method, password, and other user data. Users may also log out of their account. Logging out then causes the window opener to reload, ensuring that the user now has a logged out session.

window.admiral('show','transact.manage')

General order of operations

💡 Order may vary based on how a publisher has implemented the ad-free experience.

User arrives on publisher website.
Publisher code runs and checks for the presence of the first-party cookie that identifies that the user has an active subscription.
If that first-party cookie is present:
1. Publisher code runs that removes ads for that user.
2. Publisher code runs that changes the Login button to display Manage, and changes the event on that button to window.admiral('show',transact.manage')
If that cookie IS NOT present:
1. Ads should be displayed as normal.
When a user has logged out or the subscription expires/cancels, publisher code runs to update the first-party cookie to that of a non-subscriber.

Need more help?

If you need additional support after reviewing this guide, please email customerlove@getadmiral.com and our team will be happy to assist.