Extended Usage Tracking

The Rights Management (RM) capability can track various custom events that may be performed on a protected document. You can enable the tracking of events from the Rights Management server at the global level or at a policy level. You can then set up a JavaScript to capture specific actions performed within the protected PDF document such as clicking a button, or saving the document. This usage data is sent as an XML file in key-value pairs, which you can use for further analysis.

End users who access the protected documents can allow or decline such tracking from the client application. In the Rights Management Administration Console, each such blob is displayed as ‘Detailed Usage Tracking Data’ for the protected document.

Note: To view the events tracked, an external Auditing SPI needs to be deployed. For More information on external auditing, see Auditing events.

RightsManagement Object

This object serves as entry point for all RM-related objects, methods, and properties. An instance of a RightsManagement object can be obtained from the doc object. For example,

var obj = doc.rightsManagement;

RightsManagement Object properties

Property Name	Type	Access Type	Description
serverURL	String	READONLY	URL of the LiveCycle RM server
serverVersion	String	READONLY	Version of the LiveCycle RM server
visitorID	String	READONLY	Identifies an Acrobat installation uniquely.
isOffline	Boolean	READONLY	Is user accessing document in offline mode?
policyInfo	Object RMPolicy	READONLY	Information about RM Policy associated with document.
userInfo	Object RMUser	READONLY	Information about authenticated RM user.
documentInfo	Object RMDocument	READONLY	Info about currently open RM document.

RightsManagement Object methods

Method Name

Return Type

Description

captureEvent(String eventID, optional eventVal)

Boolean

Capture a tracking event and store it in memory. Events are sent to server only in following conditions:

1. Event queue is full (currently 25).

2. User explicitly calls flushEvents.

3. Some other event occurs that needs to be sent to server immediately.

4. User closes document.

Returns false if tracking is not enabled.

flushEvents()

Boolean

Force sends the tracking events to RM server. In case of offline access of the document, it saves the cached events in microsafe database on the user machine.

The tracking events are sent to the server when the user opens the document again in online mode.

This method returns false, if tracking is not enabled.

getTrackingStatus()

Integer

This method can be used to check if tracking is enabled for the document.

Possible return values are:

0 – Denied by LC RM server

1 – Declined by Acrobat user

2 - Allowed

Sample Code

var RMobj=this.rightsManagement;

RMobj.captureEvent("ServerURL",RMobj.serverURL);

RMobj.captureEvent("VisitorID",RMobj.visitorID);

RMobj.captureEvent("userInfo ",RMobj.userInfo.ID);

RMobj.flushEvents();

RMDocument Object

RMDocument object holds the properties of a LiveCycle RM-protected document.

RMDocument Object properties

Property Name	Type	Access Type	Description
ID	String	READONLY	ID (GUID) of the RM protected document.
expiryDate	String	READONLY	Document expiry date in UTC format. Returns “Always Valid” for perpetually valid documents.
offlineLeasePeriod	Integer	READONLY	Offline lease period.
watermarks	Array	READONLY	An array of RMWatermark objects

Sample Code

var RMobj=this.rightsManagement;

RMobj.captureEvent("Document ID ", RMobj.documentInfo.ID);

RMobj.captureEvent("VisitorID",RMobj.documentinfo.expiryDate);

RMobj.captureEvent("userInfo ",RMobj. documentinfo.offlineLeasePeriod);

RMobj.flushEvents();

RMUser Object

RMUser represents the currently authenticated user.

RMUser Object properties

Property Name	Type	Access Type	Description
ID	String	READONLY	Login name of the authenticated user. blank for Anonymous user
name	String	READONLY	Display name of the authenticated user. blank for Anonymous user
isAnonymous	String	READONLY	True in case of anonymous user.
hasEditPerm	Boolean	READONLY	Can user edit content.
hasCopyPerm	Boolean	READONLY	Can user copy content.
hasCollabPerm	Boolean	READONLY	Can user collaborate.
hasAlterPagesPerm	Boolean	READONLY	Can user delete or add pages.
hasFillAndSignPerm	Boolean	READONLY	Is digital signature allowed.
hasPrintPerm	Boolean	READONLY	Can user print content.
hasPrintLowResPerm	Boolean	READONLY	Can user print document in low resolution.
hasChangePolicyPerm	Boolean	READONLY	Can user remove security or change policy.

Sample Code

var RMobj=this.rightsManagement;

RMobj.captureEvent("ServerURL",RMobj.serverURL);

RMobj.captureEvent("userInfo ",RMobj.userInfo.ID);

RMobj.flushEvents();

RMPolicy Object

An RMPolicy object holds the properties of the RM Policy associated with the document.

RMPolicy Object properties

Property Name	Type	Access Type	Description
ID	String	READONLY	The Policy ID (GUID).
name	String	READONLY	The user-friendly policy name
description	String	READONLY	Policy description

Sample Code

var RMobj=this.rightsManagement;

RMobj.captureEvent("Policy Name",RMobj.policyInfo.name);

RMobj.captureEvent("Policy ID",RMobj.policyInfo.ID);

RMobj.flushEvents();

RMWatermark Object

Watermarks associated with the document..

RMWatermark Object properties

Property Name	Type	Access Type	Description
vertAlign	Integer	READONLY	The vertical alignment of the watermark. Possible values are: align.top, align.center, align.bottom
horizAlign	String	READONLY	The horizontal alignment of the watermark. Possible values are: align.left, align.center, align.right
vertOffset	Float	READONLY	The vertical offset of the watermark.
horizOffset	Float	READONLY	The horizontal offset of the watermark.
scale	Float	READONLY	The size of the watermark font.
rotation	Float	READONLY	”0″ to “359″. The rotation (in degrees) of the watermark.
opacity	Float	READONLY	”0.0″ to “1.0″. The opacity of the watermark.
isFixed	Boolean	READONLY	If this value is false, the watermark should be scaled to fit to the page. Otherwise, the provided scaling scale should be used.
startPage	Integer	READONLY	First page from which watermark is to be applied (first page is 0)
endPage	Float	READONLY	Last page upto which watermark is to be applied (-1 to signify all pages)
pageSelection	String	READONLY	”all”, “even” or “odd”Pages on which the watermark is to be applied.
isOnScreen	Boolean	READONLY	Watermark is displayed while viewing the document on screen.
isOnPrint	Boolean	READONLY	Watermark is printed with the document
percentage	Boolean	READONLY	Values specified with vertical and horizontal shifts are in percentage
customText	Boolean	READONLY	The custom text that is included in the watermark.
isCustomTextEnabled	Boolean	READONLY	The custom text that is included in the watermark.
isUserIDEnabled	Boolean	READONLY	Determines whether the watermark includes the user identification of the user who opens the associated document.
isUserNameEnabled	Boolean	READONLY	Determines whether the watermark includes the name of the user who opens the associated document.
isCurrentDateEnabled	Boolean	READONLY	Determines whether the watermark includes the date on which the associated document is opened.
isPolicyEnabled	Boolean	READONLY	Determines whether the watermark includes the policy with which the document is protected.
fontName	string	READONLY	Name of the font to use for the text watermark
fontSize	Float	READONLY	Size of the font to use for the text watermark
colorSpace	String	READONLY	Color space in which the color is represented
color	Array of Number	READONLY	Color of the text watermark

Sample Code

var RMobj=this.rightsManagement;

console.println("Watermarks Info");

RMobj.captureEvent("Vertical Alignment" , obj1.watermarks[0].vertAlign);

RMobj.captureEvent("Watermark Type" , obj1.watermarks[0].type);

RMobj.flushEvents();