Setting Up an Advanced Configuration
This section will outline how you can use the advanced configuration to meter a page. There are two options here depending on what you are ultimately trying to do: hybrid Integration and advanced Integration.
Hybrid Integration vs. Advanced Integration -- How do I choose?
The choice is dependent on what you are trying to do. If all you want to do is attach some logging or tracking functions to a mostly off-the-shelf Paymeter integration then you'd want to choose the Hybrid Integration approach. This approach gives you the benefits of an easy setup (Overlay behavior is already configured, etc.) with the advantage of being able to add your own functions to the Paymeter event pipeline.
If, however, you need more control over the user's experience, you would want to use the Advanced Integration. This gives you far more flexibility in how to control the paymeter but also requires quite a bit more setup and careful attention to configuration.
Setting up Hybrid Integration
The setup of a hybrid integration is very similar to the default integration described at the beginning of this document. You must still include the two html tags defined in that section (the Script tag that loads the Paymeter library and the Meta tag that defines the content).
In addition, you must add the following <script> block immediately before you load the Paymeter library:
<script>
var syncPaymeter = {
onLoad: function (meter) {…}
};
</script>
<script src='https://syncaccess-sync-demo2.stage.syncronex.com/sync/demo2/api/scripts/syncall'></script>The script block defines a variable called syncPaymeter. You must use that name exactly as shown. The variable defines a JavaScript object with one property called onLoad. Again, the property name must be typed exactly as shown in the example above. This property, in turn, is expected to be a function that will get executed by the Paymeter library when it's loaded and ready to start the authorization pipeline (the event pipeline described in the previous section).
You will need to define the function in this script block. Typically, your function will be a series of event bindings where you'll attach your own custom functionality to the various events described in the earlier chapter. The function will get a reference to the underlying PaymeterSdk object that exposes the events you'll want to handle.
The following example is an extension of the previous showing how you can attach functions (in this case, simple logging functions) to the different Paymeter events.
<script>
var syncPaymeter = {
onLoad: function(meter){
// meter is a reference to the PaymeterSdk
// bind to the session started event
meter.events.registerHandler(meter.events.onSessionStarted,
function(ctx){
var id = ctx.user.sessionId;
console.log(id);
});
// bind to the authorization success event
meter.events.registerHandler(meter.events.onAuthorizeSuccess,
function(authCtx){
var cnt = authCtx.viewCount;
var rem = authCtx.remainingViewCount;
var msg = 'view ' +
cnt.toString() +
' out of ' +
(cnt + rem).toString();
console.log(msg);
});
// log the current content id being metered:
console.log(meter.contentId);
}
};
</script>The meter argument in the example above provides the reference to the underlying PaymeterSdk. You can access the events and the configuration settings from that object (note how the content Id value is logged in the last line of the example. All of the events described in the previous section are accessible and can be accessed as described there.
A complete list of the configuration settings is described in the Advanced Integration section below.
Cancelling the Default Event Handlers
When you use the Hybrid Integration method, you will get all of the built-in event handlers that are part of the default implementation. For instance, the onWarningFired event will trigger the default event handler that is responsible for fetching and rendering a warning overlay (aka nag, aka alert). There may be times when you want to suppress that default behavior. For example, when a Warning Event is fired, you might want to present some alternative messaging to the user like an ad or a survey, etc.
You can suppress the default event handlers by returning a value of false from your custom handler. Returning false will cancel any subsequent event handlers registered for that event.
This example shows how to suppress the default warning overlay from rendering:
<!DOCTYPE html>
<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="utf-8" />
<meta name="__sync_contentCategory" content="paid" />
<title>API Tester</title>
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css">
<script src="https://code.jquery.com/jquery-2.2.4.min.js"></script>
</head>
<body>
<div class="container">
<h1>API Test</h1>
<div class="alert alert-info">
<p id="testmessage1"></p>
</div>
</div>
<script>
var syncPaymeter = {
onLoad: function (meter) {
meter.events.registerHandler(meter.events.onWarningFired,
function (ctx) {
var cnt = ctx.viewCount;
var total = ctx.viewCount + ctx.remainingViewCount;
var msg = 'User has read '
+ cnt.toString()
+ ' out of '
+ total.toString()
+ ' pages.';
$('#testmessage1').html(msg);
return false; // abort any additional handlers
});
}
}
</script>
<script src="https://syncaccess-sync-demo2.stage.syncronex.com/sync/demo2/api/scripts/syncwall?debug=true"></script>
</body>
</html>Using the Hybrid Integration in a Single Page Application (SPA)
The default and hybrid integrations of the paymeter Sdk assume that each page is metered and that the meter service should be executed on a page load event. If you are using a Single Page Application (SPA), you must manually trigger the meter calls.
You do this by defining a function within the onLoad handler as described above. Remember that the paymeter loader will call your onLoad function once after it's been loaded an initialized and is ready for event registration, etc.
The following code snippet shows how to wire up the meter call to an html button. Each time the user clicks the button, the meter will be executed and all of the events described previously will get fired just as if the page was loaded for first time.
<script>
var syncPaymeter = {
onLoad: function (meter) {
$('#btnExecute').click(function () {
meter.events.registerHandler(meter.events.onSessionStarted,
function (sessionCtx) {
sessionCtx.contentId = $('#contentId').val();
});
meter.execute(); // Fire the paymeter service
});
}
}
</script>
<script src="https://syncaccess-sync-demo2.stage.syncronex.com/sync/demo2/api/scripts/syncwall?debug=true"></script>The example also shows how the specific content category Id can be changed before firing the meter. This would be important, for instance, if your SPA is loading new "pages" with different content categories.
The example uses a button to trigger the event but you could also use another function to raise an event of your own whose handler can be defined in the onLoad event.
Using a Hybrid Configuration to Customize Plan Purchase “Origin”
This feature is only available in version 5.2.4.7-a3 or greater. Check with Syncronex support if you are unsure of your current version.
The system supports the idea of a ‘starting point from which a user enters a subscription (aka Plan) purchase workflow”. This concept is handled in a value called “Origin”. The origin is just a piece of text that can be used to describe this starting point. This origin value can be included on links to the purchase page (part of the subscription/activation workflow) and then reported on to see from where your users are being enticed to purchase.
The default configuration of Paymeter uses a generic value for the origin when users select plans from any of the overlays (wall, alert, inline). For example, if a user purchases a plan that she saw on a modal paywall overlay, the origin would be set to ‘paywall’. Administrators would be able to see how many users are purchasing plans that were exposed on the ‘paywall’ but that might not be detailed enough.
Customers that wish to have more precise control over origin values can use the Hybrid configuration to supply their own origin values. For example, rather than simply knowing a plan was purchased via the “paywall”, you might want to know that the plan was purchased from “the paywall that fired on the sports section of the website”. Of course, you’d want to use an origin value a bit more ‘programmatic’ than that.
If you want to override the default origin values, you must supply an implementation of a special function called getOrigin. You do this the same way you provide an implementation for the onLoad function when setting up the Hybrid configuration. Here’s an example that shows a custom implementation:
<script>
var syncPaymeter = {
getOrigin: function(overlayContext){
// Implementation here that returns origin
}
};
</script>
<script src=https://syncaccess-sync-demo2.stage.syncronex.com/sync/demo2/api/scripts/syncwall?debug=true></script>The value returned from your custom implementation must be a text value. You can’t return an object, function, etc.
Your custom function will be called and passed a overlayContext object which gives you some minimal but useful information about the overlay that is intended to be shown to the user. This might be a modal ‘wall’, or a dismiss-able ‘alert’ and you may want to tailor your function based on this data. The overlayContext object looks like this:
{
contentId: string,
type: string,
defaultOrigin: function
}| contentId | String | The currently-configured contentId used to fetch the overlay. |
| Type | String | Describes the kind of overlay being rendered. Possible values are ‘wall’, ‘alert’, or ‘inline’ |
| defaultOrigin | Function | A function that will return the underlying default origin value that is normally used in the overlay. |
You can safely ignore the overlayContext object if you do not need any of its values.
The following code snippet is a more complete example of using a custom origin in order to supply a consistent value to an external analytics package and to the Syncronex paymeter:
<script>
function computeOriginToUseForTracking(){
return 'CustomOrigin';
}
var syncPaymeter = {
onLoad: function (meter) {
meter.events.registerHandler(meter.events.onWallFired,
function(meterContextObject) {
var originForAnalytics = computeOriginToUseForTracking();
// send origin value to analytics...
trackSyncMeterEvent('wall',originForAnalytics);
});
},
getOrigin: function (overlayContext) {
var originForSyncronex = computeOriginToUseForTracking();
// send origin value to syncronex metering for purchase tracking
return originForSyncronex;
}
};
</script>
<script src=../api/scripts/syncwall?debug=true></script>
Setting up an Advanced Configuration
You can interact directly with the PaymeterSdk.js library if you want full control over the authorization process and any resulting UX. In this mode, you are responsible for handling the server authorization responses by registering functions with the onAuthorizeSuccess and onAuthorizeFailed events.
To use the Paymeter sdk directly, you must include a reference to the library:
<script src=http://cdn.syncronex.com/libs/v0.1/syncPaymeterSdk.js></script>Once the library is loaded, you'll be able to interact with the Paymeter Sdk through the window.syncPaymeterSdk object.
Triggering a Paymeter authorization process requires 3 steps:
- Setup the Paymeter configuration
- Execute the Authorize function
- Handle the authorization events for success and failure.
Setup the Paymeter Configuration
There are several configuration properties exposed by the Paymeter Sdk. Some of these properties have reasonable default values so that you don't have to worry about them unless you need to override default behavior. Other properties are required in order for the Sdk to function properly. A complete list of the properties is shown here along with the default values and information regarding whether you'll need to explicitly set the property.
| Property | Description | Default Value | Required/Optional |
| contentId | The specific content category that is being authorized. | Empty | Required |
| apiBaseUrl | Tells the Sdk to which property-specific service you are authorizing against. You should expect to receive an explicit URL to use here. Each customer and property are assigned to a unique instance of the Paymeter system and have their own specific url. |
Empty | Required |
| enableHistory | Flag (true/false) indicating whether or not you want to allow the users viewing history to influence the Paymeter calls (see below) | True | Optional |
| sessionExpireDays | Total number of days to keep an anonymous userId and other session information cached. If the session expires, the user will get a new session on the next call to the server and all of her view counts, etc. will be reset. It's unlikely you'd need to change this except during development and testing. | 36500 (100 years) | Optional |
| cookiePath | Specific path under the current domain to which you want to write the session cookie. | / (root) | Optional |
| apiTimeout | Number of milliseconds after which the Sdk will abort the server authorization call. |
3000 (3 seconds) |
Optional |
| instanceKey | Reserved for Future use | Empty | Optional |
| applicationKey | Reserved for Future use | Empty | Optional |
| channel | Reserved for future use | Empty | Optional |
| referringPage* | The specific referring page from which the user navigated to get to your custom meter page. | document.referrer | Required |
* important note regarding the 'referringPage' value: The paymeter service must have a value for referringPage in order to process all of the metering rules (several of which depend on a referrer). The syncPaymeterSdk.js library will look for document.referrer by default but if there is no referring page at all, this will trigger an error. You must ensure that a referringPage value is set even if there was no actual referring page. This is a known limitation in the current version of the SDK. You can easily work around this limitation by providing a value for this property via an event handler. The onSessionStarted event is fired once the sdk has fetched all of the current session context. You can intercept this event and add the referringPage like this:
<script src=http://cdn.syncronex.com/libs/v0.1/syncPaymeterSdk.js></script>
<script>
var sdk = window.syncPaymeterSdk; // get a more manageable handle to sdk
sdk.events.registerHandler(sdk.events.onSessionStarted,
function (ctx) {
ctx.referringPage = document.referrer || window.location.toString();
});
</script>The following shows a complete example of initializing the Sdk:
<script src=http://cdn.dev.syncronex.com/libs/v0.1/syncPaymeterSdk.js />
<script>
var sdk = window.syncPaymeterSdk; // get a more manageable handle to sdk
sdk.apiBaseUrl = 'https://syncaccess-sync-demo2.stage.syncronex.com/appservices';
sdk.debug = true; // debug mode
sdk.enableHistory = false; // turn off history
sdk.apiTimeout = 5000; // increase timeout
sdk.contentId = 'sports'; // set the content to authorize
// Setup the events to handle the authorization results
sdk.events.registerHandler(sdk.events.onSessionStarted,
function (ctx) {
ctx.referringPage = document.referrer || window.location.toString();
});
sdk.events.registerHandler(sdk.events.onAuthorizeSuccess,
function(authResult){
console.log('user is authorized');
});
sdk.events.registerHandler(sdk.events.onAuthorizeFailed,
function(authResult){
console.log('user not authorized');
window.location.href='http://acme.com/subscribe.html';
});
</script>Execute the Authorization Function
Once the configuration is set and you've registered your callback functions to handle the server responses, you need to tell the Sdk to go ahead and start the authorization process. You call the execute method on the Sdk to trigger the authorization process.
<script src=http://cdn.dev.syncronex.com/libs/v0.1/syncPaymeterSdk.js />
<script>
var sdk = window.syncPaymeterSdk; // get a more manageable handle to sdk
// configure sdk and register events...
sdk.execute(); // trigger the authorization process
</script>The execute() function will start the authorization process and trigger the events described earlier in Paymeter Events. You can create callback functions to respond to any of the events described in that section.
Complete Example
<!DOCTYPE html>
<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="utf-8" />
<title>SDK Test | Advanced Mode</title>
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css">
<script src="https://code.jquery.com/jquery-2.2.4.min.js"></script>
</head>
<body>
<div class="container">
<h1>API Test</h1>
<div class="alert alert-info">
<p id="testmessage0"></p>
<p id="testmessage1"></p>
</div>
</div>
<script src="http://cdn.syncronex.com/libs/v0.1/syncPaymeterSdk.js"></script>
<script>
function setAuthorizeMessage(isAuthorized) {
var $el = $('#testmessage0');
var msg = 'User is ' + (isAuthorized ? '' : 'NOT') + ' authorized';
$el.html(msg);
}
var sdk = window.syncPaymeterSdk;
sdk.apiBaseUrl = 'https://syncaccess-sync-demo2.stage.syncronex.com/appservices/';
sdk.debug = true; // debug mode
sdk.enableHistory = false; // turn off history
sdk.apiTimeout = 5000; // increase timeout
sdk.contentId = 'paid'; // set the content to authorize
// Setup the events to handle the authorization results
sdk.events.registerHandler(sdk.events.onSessionStarted,
function (sessionCtx) {
sessionCtx.referringPage = window.location.toString();
});
sdk.events.registerHandler(sdk.events.onAuthorizeSuccess,
function (authResult) {
console.log('user is authorized');
setAuthorizeMessage(true);
});
sdk.events.registerHandler(sdk.events.onAuthorizeFailed,
function (authResult) {
console.log('user not authorized');
setAuthorizeMessage(false);
});
sdk.events.registerHandler(sdk.events.onWarningFired,
function (ctx) {
var cnt = ctx.viewCount;
var total = ctx.viewCount + ctx.remainingViewCount;
var msg = 'User has read ' + cnt.toString() + ' out of ' + total.toString() + ' pages.';
$('#testmessage1').html(msg);
});
sdk.execute();
</script>
</body>
</html>