Device Mode

Allows a defined number of devices, and blocks the others. A user is allowed to read only if the maximum number of devices is not reached.

Device Mode without any blocking, just monitoring

User journeys

• You have decided to allow your subscribers to read your articles simultaneously on up to two devices.
• USER 1 is reading an article.
• USER 2 is reading an article at the same time with USER 1 account.
• USER 3 wants to read an article at the same time with USER 1 account. At this moment, Capping is detecting those two devices are used at the same time, 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 devices, without any blocking.

<script>
  var siriusCapping = window.siriusCapping || {};
  siriusCapping.config = {
    brand: "<BRAND_UUID>", //mandatory
    userId: "<THE_USER_ID>", //mandatory
    mode: "device",
    tolerance: 2, //default: 1
  };
</script>
<script async src="https://capping.sirius.press/sdk.v1.1.0.js"></script>

Note: Declaring siriusCapping.config.brand and siriusCapping.config.userId will automatically launch simultaneous devices 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.

Since the default behavior is reading mode, you must create a configuration instance to modify it.

var configuration = CappingConfiguration()
configuration.mode = .device

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

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.

Since the default behavior is reading mode, you must use the setMode() method to change the global value of the capping mode.

val capping = Capping.getInstance(applicationContext)
capping.initialize("https://capping.sirius.press", "<api-key>")
capping.setMode(CappingMode.DEVICE)

Device Mode with blocking

User journeys

• You have decided to allow your subscribers to read your articles simultaneously on up to two devices.
• USER 1 is reading an article.
• USER 2 is reading an article at the same time with USER 1 account.
• USER 3 wants to read an article at the same time with USER 1 account. At this moment, Capping is detecting that the first user is reading, so USER 2 is blocked.

JavaScript integration

You are responsible for building the UI that blocks content when a simultaneous reading is detected. Here is an example of how you can do it, by adding the following lines in your html, wherever you want.

<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="siriusCapping.continueReading()">Continue reading</a>
</div>

• siriusCapping.continueReading(): This function is defined by JavaScript SDK and allows you to restart Capping when a user is blocked.
• siriusCapping.stop(): Besides, if you want to stop Capping for any reason, you can siriusCapping.stop() function anywhere, then use siriusCapping.continueReading() to restart Capping

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 showPopinFunction when a simultaneous reading is detected. Defining showPopinFunction obliges you to define hidePopinFunction as well, because a popin must appear when a simultaneous reading is detected, but it must also disappear at the right time.

<script>
  var siriusCapping = window.siriusCapping || {};
  siriusCapping.config = {
    brand: "<BRAND_UUID>", //mandatory
    userId: "<THE_USER_ID>", //mandatory
    mode: "device",
    tolerance: 2, //default: 1

    // showPopinFunction function helps you to display something to block reading
    // It is just an example, feel free to change it as you want
    showPopinFunction: function () {
      x = document.getElementById("capping");
      x.style.display = "block";
    },
    // hidePopinFunction function helps you to hide the previous showed popin
    hidePopinFunction: function () {
      x = document.getElementById("capping");
      x.style.display = "none";
    },
  };
</script>
<script async src="https://capping.sirius.press/sdk.v1.1.0.js"></script>

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()).

Track conversions

Your popin will help generate conversions or upsell. To reconcile your conversions with popin displays, you can ask Capping SDK to only collect a conversion (without launching any simultaneous reading tracking). For example, here's how to do it on your purchase confirmation page.

<script>
  var siriusCapping = window.siriusCapping || {};
  siriusCapping.config = {
    brand: "<BRAND_UUID>", //mandatory
    userId: "<THE_USER_ID>", //mandatory
    mode: "conversion",
  };
</script>
<script async src="https://capping.sirius.press/sdk.v1.1.0.js"></script>

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)

Track conversions

In order to track a conversion event on iOS you can use the trackConversionEvent method.

self.cappingService.trackConversionEvent()

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)

Track conversions

In order to track a conversion event on Android you can use the trackConversionEvent method.

this.capping.trackConversionEvent()

Events & Getters

Javascript integration

The Javascript integration provides events and functions that allow you to monitor the current state of connected devices in real time.

Connected Device Count

Track the number of connected devices for a user:

Event

window.addEventListener("capping:connectedDeviceCount", (e) => {
  console.log("Connected devices:", e.detail.count);
});

Getter

const count = siriusCapping.getConnectedDeviceCount();
// returns a number or null if mode is not 'device'