Reading Mode

Detects simultaneous reading by a subscriber on multiple devices. The last user who read is allowed, the others are blocked.

Reading Mode without any blocking, just monitoring

User journeys

  • USER 1 is reading an article.
  • USER 2 is authenticated with USER 1 account and he is reading an article. At this moment, Capping is detecting 1 simultaneous readings, but no blocking message is displayed.

JavaScript integration

Add following lines into your html, just before the closing body tag. This javascript sdk integration launch tracking of simultaneous readings, without any blocking.

<script>
var CAPPING_CONFIG = {
brand: "<BRAND_UUID>", //mandatory
userId: "<THE_USER_ID>", //mandatory
mode: "reading",
};
</script>
<script async src="https://capping.sirius.press/sdk.v1.0.0.js"></script>
ParamTypeDescription
CAPPING_CONFIG.brandstringA brand uuid that we'll give you
CAPPING_CONFIG.userIdstringThe ID of the user, that you can write encrypted or hashed
CAPPING_CONFIG.modestringTwo modes are available, reading (default) and device

Note: Declaring CAPPING_CONFIG.brand and CAPPING_CONFIG.userId will automatically launch simultaneous readings tracking. If you don’t want to launch Capping, do not define these variables and/or do not insert the javascript sdk.

iOS integration

Create the capping service and store it in a property. Don't create a new instance every time you need it, use the same instance throughout the lifecycle of the app.

Make sure to set the user id or the tracking will not work.

let baseURL = URL(string: "https://capping.sirius.press")!
let cappingService = CappingService(baseURL: baseURL, apiKey: "<api-key>")
cappingService.setUserId("<user-id>")
self.cappingService = cappingService

By default, the SDK does nothing. You must call startSession() and stopSession() in order to start and stop the tracking of simultaneous sessions.

You can either call startSession() when the app is opened and stopSession() when it is closed, or you can fine tune “reading sessions” for example by calling startSession() when an article is opened and stopSession() when it is closed.

Android integration

Initialize the capping SDK at application launch and use the getInstance() method when you need to access the shared instance later.

Make sure to set the user id or the tracking will not work.

val capping = Capping.getInstance(applicationContext)
capping.initialize("https://capping.sirius.press", "<api-key>")
capping.setUserId("<user-id>")

By default, the SDK does nothing. You must call startSession() and stopSession() in order to start and stop the tracking of simultaneous sessions.

You can either call startSession() when the app is opened and stopSession() when it is closed, or you can fine tune “reading sessions” for example by calling startSession() when an article is opened and stopSession() when it is closed.

Reading Mode with blocking

User journeys

  • USER 1 is reading an article.
  • USER 2 is authenticated with USER 1 account and he is reading an article. At this moment, Capping is detecting 1 simultaneous readings, and a message is displayed to USER 1.

JavaScript integration

Add following lines into your html where you want to display blocking message when simultaneous readings is detected.

<div id="capping" style="display: none">
<p>Your subscription is used on another device.</p>
<h3>You can only use your account on one device at the same time</h3>
<a href="#" onclick="restartCapping()">Continue reading</a>
</div>
  • restartCapping(): This function is defined by javascript sdk and allows you to restart Capping when a user is blocked.

Then, add following lines into your html, just before the closing body tag. This javascript sdk integration launch tracking of simultaneous readings, and will execute togglePopinFunction when a simultaneous readings will be detected.

<script>
var CAPPING_CONFIG = {
brand: "<BRAND_UUID>", //mandatory
userId: "<THE_USER_ID>", //mandatory
mode: "reading",
// this function helps you to display something to block reading
// It is just an example, feel free to change it as you want
togglePopinFunction: function () {
x = document.getElementById("capping");
if (x.style.display === "none") {
x.style.display = "block";
} else {
x.style.display = "none";
}
},
};
</script>
<script async src="https://capping.sirius.press/sdk.v1.0.0.js"></script>
ParamTypeDescription
CAPPING_CONFIG.brandstringA brand uuid that we'll give you
CAPPING_CONFIG.userIdstringThe ID of the user, that you can write encrypted or hashed
CAPPING_CONFIG.modestringTwo modes are available, reading (default) and device
CAPPING_CONFIG.togglePopinFunctionfunctionThis function will be called when a simultaneous readings will be detected. It helps you to display messages, popin, banner...

iOS integration

Make sure to follow the integration without blocking first. Then add an observer with callbacks to be notified when the lock status changes. You are responsible for building the UI that blocks the content.

private func setupObserver() {
let selector = #selector(lockStatusDidChange(_:))
self.cappingService.addObserver(self, selector: selector)
}
@objc private func lockStatusDidChange(_ notification: Notification) {
switch self.cappingService.lock {
case .blocked(_):
print("Session changed to LOCKED")
// Block content
case .unblocked:
print("Session changed to UNLOCKED")
// Unblock content
}
}

If your UI allows the user to manually unblock the content, when they do so you must restart the session using the continueReading() method, not the startSession() method.

Note: If the session becomes unlocked while the blocking UI is displayed, and you react to the lock change by hiding the blocking UI, this may cause the blocking UI to be displayed and hidden before the user has time to read its content, which way be an undesirable behavior depending on your use case.

By default the lock status will always stay .blocked at least 10 seconds before switching to .unblocked, even if the session is unlocked before this delay. You can change this value using the blockingMinDelay property of the CappingConfiguration object.

Alternatively you can set autoUnblock to false on the CappingService. In that case the lock status will never switch back to .unblocked on its own (you have to call continueReading()).

Android integration

Make sure to follow the integration without blocking first. Then add a listener to be notified when the lock status changes. You are responsible for building the UI that blocks the content.

this.listener = object : CappingLockStatusListener {
override fun onLockChange(cappingLock: CappingLock) {
when (cappingLock) {
is CappingLock.Blocked -> {
// Block content
}
is CappingLock.Unblocked -> {
// Unblock content
}
}
}
}
this.capping.attachListener(this.listener)

If your UI allows the user to manually unblock the content, when they do so you must restart the session using the continueReading() method, not the startSession() method.

Note: If the session becomes unlocked while the blocking UI is displayed, and you react to the lock change by hiding the blocking UI, this may cause the blocking UI to be displayed and hidden before the user has time to read its content, which way be an undesirable behavior depending on your use case.

By default the lock status will always stay Blocked at least 10 seconds before switching to Unblocked, even if the session is unlocked before this delay. You can change this value using the blockingMinDelay property of the CappingSDKConfiguration object.

Alternatively you can call setAutoUnblock(false) on Capping. In that case the lock status will never switch back to Unblocked on its own (you have to call continueReading()).

Reading Mode with blocking but tolerance

Tolerance number define number of simultaneous readings by user per day, from which blocking will start.

User journeys

Let's imagine that we have defined a tolerance of 3 simultaneous readings

  1. USER 1 is reading an article.
  2. USER 2 is authenticated with USER 1 account and he is reading an article. At this moment, Capping is detecting 1 simultaneous readings, but no blocking message is displayed.
  3. USER 1 is reading a new article and a 2nd simultaneous readings is detected, but no blocking message is displayed.
  4. USER 3 is authenticated with USER 1 account and he is reading an article. At this moment, a 3rd simultaneous readings is detected, and a message is displayed to USER 1 and USER 2

JavaScript integration

Add following lines into your html where you want to display blocking message when simultaneous readings is detected.

<div id="capping" style="display: none">
<p>Your subscription is used on another device.</p>
<h3>You can only use your account on one device at the same time</h3>
<a href="#" onclick="restartCapping()">Continue reading</a>
</div>

Then, add following lines into your html, just before the closing body tag. This javascript sdk integration launch tracking of simultaneous readings, and will execute togglePopinFunction when the tolerance of simultaneous readings by user per day will be achieved.

<script>
var CAPPING_CONFIG = {
brand: "<BRAND_UUID>", //mandatory
userId: "<THE_USER_ID>", //mandatory
mode: "reading",
tolerance: 3,
togglePopinFunction: function () {
x = document.getElementById("capping");
if (x.style.display === "none") {
x.style.display = "block";
} else {
x.style.display = "none";
}
},
};
</script>
<script async src="https://capping.sirius.press/sdk.v1.0.0.js"></script>
ParamTypeDescription
CAPPING_CONFIG.toleranceintNumber of simultaneous readings by user per day, from which blocking will start.

iOS integration

Make sure to follow the integration with blocking first. Then use the setTolerance() method, to change the global value of the tolerance.

self.cappingService.setTolerance(3)

Android integration

Make sure to follow the integration with blocking first. Then use the setTolerance() method, to change the global value of the tolerance.`

this.capping.setTolerance(3)
Edit this page on GitHub