Extended Usage Tracking

Share

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 the Auditing SPI blog post.

RightsManagement Object

A new object of type RightsManagement has been introduced. 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 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 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  0.0″ to “1.0″. 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();

Author: Salma Shaikh
Editor: Ivan David Vaseekaran

Share