Vidi Docs

Welcome

Vidi is the only enterprise offering of native PDF tracking for security and analytics. We enable a better understanding of how documents are read and by who, without breaking the portability of a PDF document itself.

Support

Supporting our developers and users is extremely important to us. If you have any feedback, questions, and or issues we are here for you.

Vidi Features

This chapter focuses on a quick overview of our most valuable features.

Native Tracking

While document formats have varied over the past decade, PDF has continued to remain popular in a host of industries. They remain a standard in document portability, storage, feature richness, and accessibility.

Document tracking solutions come in two distinct flavors. First and the most popular being web based where the document is in the format of a webpage. The second is a DRM plugin installed on the viewer device. Both of these options break the chain of trust as to what a PDF is and how it’s read. Webpages are not a PDF, they cannot be saved or stored/processed similar to the native file.

Vidi tracks the native file itself, we enable tracking within Adobe Acrobat without any additional required software. It enables enterprises to use preferred file storage solutions (SharePoint, HubSpot) without any infrastructure/process changes.

Native tracking offers a frictionless experience in both security and analytics of native PDF documents.

Forced Tracking

Tracking availability while is robust, is not always possible due to device environments. In use cases where the contents of the PDF should only be accessed when tracked, we include a toolset named Forced Tracking Mode.

When Forced Tracking Mode is enabled via the Dashboard or API, the document’s contents are only accessible when the document successfully connects to Vidi services and tracking initiates. This ensures content can not be viewed on non-tracked PDF readers, offline reading, and or if the user does not agree to tracking.

This feature can include a custom error message if the contents are not accessible. See Modify Document Settings within the Documents REST API.

User communication and transparency is important. We have included a customizable dialog box that enables custom text, icon choice, and more precise enable/disable of tracking.

GDPR Privacy Dialog Screenshot

For enabling and customizing the privacy dialog box, see Modify Document Settings within the Documents REST API.

Error Messages

When Forced Tracking Mode is enabled, error messages are displayed on non-tracked PDF readers. We support various variables and BBCode formatting.

Currently only URL BBCode is supported.

Example:
[url=https://vidi.fyi]Our Website[/url]

Variable	Description	Example
#WebView	Link to tracked web view of PDF	documentloading.com/viewer/{id generated on PDF conversion}}
#ID	ID of PDF	{id generated on PDF conversion}
#PDFName	Name of PDF including file extension	example.pdf
#OpenAcrobat	Open Acrobat from url experimental	none

See Modify Document Settings within the Documents REST API.

Tracking Methodologies

No specific method of PDF tracking fits all device ecosystems or goal requirements. This section is an overview of differing tracking methods and their intended use case.

Native

Native PDF tracking utilizes features mostly only available in fully featured PDF readers such as Adobe Acrobat.

This is a compromise of tracking for keeping the document in its native format and it’s portability as a file. Using Forced Tracking Mode, this can mitigate the lack of tracking availability in most readers.

Web

Using a web-based PDF reader, we enable PDF tracking within the browser. This provides a frictionless experience of opening a document via a link and a highly robust tracking solution that works across all platforms and devices.

The majoring difference is tracking is done on the reader level, instead of within the PDF itself.

For finding endpoints for a tracked PDF, see Document Endpoints within the Documents REST API.

Hybrid

Combining both native and web tracking produces a highly resilient methodology capable of all devices and ensuring the document is tracked when saved to the device itself.

Users are able to view the PDF within a browser, while also downloading it to their local device. Tracking persists allowing for a full contextual story of a document’s journey viewed in native PDF readers.

Hybrid Tracking Diagram

Obtained Data

List of data obtained via sessions/events.

Session

Node	Description
`ip`	IPv4/v6 address of viewer
`user_agent`	User agent, viewer device info
`hostname`	Domain attached to IP, can be IPv4/v6
`created_at`	Timestamp generated at creation of session
`updated_at`	Timestamp updated when change within session occurs

Events

Event	Description
`viFrame`	Both initial and keep alive event
`viPrint`	Registered when a preview/physical print event occurs
`viLink`	Registered when a URL is clicked

viFrame

Both initial and keep alive event. viFrame is fired within every 3-5 seconds during a session.

Node	Description
`id`	Event id
`session_id`	Session UUID
`type`	Event type
`currentPage`	Current page in view of the PDF viewer, starting page is 0
`currentZoom`	Current zoom level of PDF viewport in percent
`currentZoomType`	Name of current zoom type reflected by currentZoom Due to the inconsistency of Acrobat vs browser, the zoom name type can vary and possibly be null in web sessions
`location`	File path document was viewed at location often contains viewers OS user account, only present if viewed in Adobe Acrobat otherwise browser URL or null
`pageViewRect`	The pages rectangle expressed in lower-left x, lower-left y, upper-right x, upper-right y pageViewRect can be used to determine page size at time of viewing, it’s coordinates are not based on screenspace.
`mouseX`	Mouse x position at time of event, coordinate system is within pageViewRect
`mouseY`	Mouse y position at time of event, coordinate system is within pageViewRect
`created_at`	Timestamp generated at creation of event
`updated_at`	Timestamp updated when change within event occurs

Example viFrame

[
  { 
    "events": [ 
      { 
        "id": "f04ca01136454744beb958272ca5b328",
        "session_id": "9e324f4a99804bde9affd58a1318f314",
        "type": "viFrame",
        "event": { 
          "mouseX": 300,
          "mouseY": -1684,
          "currentPage": 0,
          "currentZoom": 125,
          "pageViewRect": "127, -1417, 1137, 2846",
          "currentZoomType": "auto"
        },
          "created_at": "2020-01-14 22:44:09",
          "updated_at": "2020-01-14 22:44:09"
        }
      ]
  }
]

viPrint

Registered when a print preview or physical print event occurs.

Some browsers include inconstancies where print preview and printing can fire simultaneously multiple times within a short time span. Printing events in web browser sessions should only be understood as either printed or not printed.

If print event was within Acrobat, the print type can be trusted with accuracy.

Node	Description
`id`	Event id
`session_id`	Session UUID
`type`	Event type
`printType`	Print type 0 - Print error 1 - Print preview 2 - Print job
`created_at`	Timestamp generated at creation of event
`updated_at`	Timestamp updated when change within event occurs

[
  { 
    "events": [ 
      { 
        "id": "4019f0251232c89b8646b9fb1af9c2ce",
        "session_id": "454afbc06c8eee0a8e2007c593c1d34b",
        "type": "viPrint",
        "event": { 
          "printType": 1
          }
        },
          "created_at": "2020-01-14 22:44:09",
          "updated_at": "2020-01-14 22:44:09"
      ]
  }
]

viLink

Registered when a user interacts with a PDF link for both internal/external URLs. The event is reported with the PDF object ID as designated within the structure of the PDF.

Node	Description
`id`	Event id
`session_id`	Session UUID
`type`	Event type
`annoId`	PDF Object ID
`created_at`	Timestamp generated at creation of event
`updated_at`	Timestamp updated when change within event occurs

[
  { 
    "events": [ 
      { 
        "id": "40040ed37b58373b80039df5c88f1b68",
        "session_id": "454afbc06c8eee0a8e2007c593c1d34b",
        "type": "viLink",
        "event": { 
          "annoId": "2899R"
          }
        },
        "created_at": "2020-01-14 22:44:09",
        "updated_at": "2020-01-14 22:44:09"
      ]
  }
]

Authorization

Vidi utilizes a static token generated with your account for API access. Authorization is required as a Bearer token defined in the consumers header.

Without authorization, expect a 401 – Unauthorized/403 – Forbidden.

$ curl -X GET -H "Accept: application/json" -H "Authorization: Bearer {token}" https://api.vidi.fyi/v1/

Users

Multiple users is a planned feature, all actions are defaulted to DefaultUser.

List Users

List users associated with token.

GET

/v1/users/

Example Request

$ curl -X GET -H "Accept: application/json" -H "Authorization: Bearer {token}" https://api.vidi.fyi/v1/users/

Example Response

[
  {
    "Users": "DefaultUser"
  }
]

Documents

This section is specific to document actions.

List Settings

List global settings for future tracked documents.

GET

/v1/documents/settings

Example Request

$ curl -X GET -H "Accept: application/json" -H "Authorization: Bearer {token}" https://api.vidi.fyi/v1/documents/settings/

Example Response

[
  { 
    "ForcedTracking": false,
    "ForcedTrackingErrorMsg": "Denied Access\nUse Adobe Acrobat",
    "ForcedTrackingCheckingCon": "Getting document...",
    "ForcedTrackingDisabledCon": "You are not connected to the internet.",
    "PrivacyDialog": false,
    "PrivacyDialogTitle": null,
    "PrivacyDialogIconType": 2,
    "PrivacyDialogMsg": null
  }
]

Modify Settings

Modify global settings that effect all future tracked documents. Documents that are processed before a change will remain unaffected.

Name	Possible Type	Description
`ForcedTrackingErrorMsg`	`string`, `null`	Message displayed when Forced Tracking Mode is enabled and PDF can not be tracked. \n, variables, and BBCode are supported.
`ForcedTrackingCheckingCon`	`string`, `null`	Message displayed when Forced Tracking Mode is enabled and PDF is checking tracking availability. \n, variables, and BBCode are supported.
`ForcedTrackingDisabledCon`	`string`, `null`	Message displayed when Forced Tracking Mode is enabled and tracking is not available. \n, variables, and BBCode are supported.
`PrivacyDialog`	`bool`	Toggles GDPR Privacy Dialog.
`PrivacyDialogTitle`	`string`, `null`	Title of GDPR Privacy Dialog.
`PrivacyDialogMsg`	`string`, `null`	Text within GDPR Privacy Dialog. Newline characters, BBCode are not supported.
`PrivacyDialogIconType`	`int`	Icon of GDPR Privacy Dialog 0 – Error (default) 1 – Warning 2 – Question 3 – Status Note: Mac OS, no distinction is made between warnings and questions.

POST

/v1/documents/settings

Example Request

$ curl -X POST -H "Accept: application/json" -H "Authorization: Bearer {token}" -d "{ "ForcedTracking": true }" https://api.vidi.fyi/v1/documents/settings/

Example Response

[
  { 
    "ForcedTracking": true,
    "ForcedTrackingErrorMsg": "Denied Access\nUse Adobe Acrobat",
    "ForcedTrackingCheckingCon": "Getting document...",
    "ForcedTrackingDisabledCon": "You are not connected to the internet.",
    "PrivacyDialog": false,
    "PrivacyDialogTitle": null,
    "PrivacyDialogIconType": 2,
    "PrivacyDialogMsg": null
  }
]

List Documents

List documents associated with user.

GET

/v1/documents/

Example Request

$ curl -X GET -H "Accept: application/json" -H "Authorization: Bearer {token}" https://api.vidi.fyi/v1/documents/

Example Response

[
  {
    "Documents":[
      {
        "id": "9bf33ce0392a43bd89b40fcb4674a4a2",
        "original_name": "Swan.pdf",
        "nick_name": null,
        "updated_at":{
          "date": "2020-01-14 22:09:09.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        },
        "created_at":{
          "date": "2020-01-14 19:58:33.000000",
          "timezone_type": 3,
          "timezone":"UTC"
        }
      },
      {
        "id":"nd0afecb07c15b5093d858cbegd4e2ba",
        "original_name": "Ant.pdf",
        "nick_name": null,
        "updated_at": {
          "date": "2020-01-14 17:52:53.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        },
        "created_at":{
          "date": "2019-02-20 07:12:14.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        }
      }
    ]
  }
]

Upload Document

Upload document

Property	Description
`document`	location of PDF

POST

/v1/documents/

Example Request

$ curl -X POST -H "Authorization: Bearer {token}" -F "document=@/Users/Jacob/Docs/sample.pdf" https://api.vidi.fyi/v1/documents/

Example Response

[
  {
    "Documents":[
      {
        "id": "9bf33ce0392a43bd89b40fcb4674a4a2",
        "original_name": "Swan.pdf",
        "nick_name": null,
        "updated_at":{
          "date": "2020-01-14 22:09:09.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        },
        "created_at":{
          "date": "2020-01-14 19:58:33.000000",
          "timezone_type": 3,
          "timezone":"UTC"
        }
      }
    ]
  }
]

Retrieve Document

Retrieve metadata associated with document.

GET

/v1/documents/{id}

Example Request

$ curl -X GET -H "Accept: application/json" -H "Authorization: Bearer {token}" https://api.vidi.fyi/v1/documents/{id}/

Example Response

[
  {
    "Documents":[
      {
        "id": "9bf33ce0392a43bd89b40fcb4674a4a2",
        "original_name": "Swan.pdf",
        "nick_name": null,
        "updated_at":{
          "date": "2020-01-14 22:09:09.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        },
        "created_at":{
          "date": "2020-01-14 19:58:33.000000",
          "timezone_type": 3,
          "timezone":"UTC"
        }
      }
    ]
  }
]

Delete Document

Delete metadata and document associated with document.

If successful, will return 200.

DELETE

/v1/documents/{id}/

Example Request

$ curl -X DELETE -H "Accept: application/json" -H "Authorization: Bearer {token}" https://api.vidi.fyi/v1/documents/{id}/

Tracked Document

Returns tracked PDF (binary blob) using the current global settings.

GET

/v1/documents/{id}/pdf/

Example Request

$ curl -X GET -H "Authorization: Bearer {token}" https://api.vidi.fyi/v1/documents/{id}/pdf/

Document Endpoints

List of endpoints that enable tracking. This can be Native PDF Tracking and or Web Tracking.

GET

/v1/documents/{id}/endpoints/

Example Request

$ curl -X GET -H "Accept: application/json" -H "Authorization: Bearer {token}" https://api.vidi.fyi/v1/documents/{id}/endpoints/

Example Response

[
  { 
    "Endpoints": [ 
      "pdf",
      "https://documentloading.com/viewer/9bf33ce0392a43bd89b40fcb4674a4a2"
    ]
  }
]

Sessions

Sessions are the instance of time a viewer reads a document. They are correlated by either document id or the persistent viewer id.

If a user closes a document but reopens it within 15 minutes, this will be considered the same session.

List Sessions

List sessions associated with document.

GET

/v1/documents/{id}/sessions/

Example Request

$ curl -X GET -H "Accept: application/json" -H "Authorization: Bearer {token}" https://api.vidi.fyi/v1/documents/{id}/sessions

Example Response

[
  {
    "Sessions":[
      {
        "id": "3159e119ccd64bafa03057f136a78554",
        "doc_id": "9bf33ce0392a43bd89b40fcb4674a4a2",
        "viewer_id": "1fdf44c801094655a327df95fc893cb2",
        "ip": "172.93.12.18",
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML,  like Gecko) Chrome/79.0.3945.117 Safari/537.36",
        "hostname": "172.93.12.18",
        "created_at": "2020-01-14 20:02:24",
        "updated_at": "2020-01-14 21:06:45"
      },
      {
        "id": "565154b6f7e842bb93153cf59c4f9226",
        "doc_id": "9bf33ce0392a43bd89b40fcb4674a4a2",
        "viewer_id": "a9da1a2e222747b9ba973971c5174338",
        "ip": "172.93.12.18",
        "user_agent": "Mozilla/3.0 (compatible; Acrobat Annots 19.21.20058 )",
        "hostname": "172.93.12.18",
        "created_at": "2020-01-14 20:00:24",
        "updated_at": "2020-01-14 20:01:13"
      }
    ]
  }
]

Retrieve Session

Retrieve metadata associated with session.

GET

/v1/documents/{id}/sessions/{id}/

Example Request

$ curl -X GET -H "Accept: application/json" -H "Authorization: Bearer {token}" https://api.vidi.fyi/v1/documents/{id}/sessions/{id}/

Example Response

[
  {
    "Sessions":[
      {
        "id": "3159e119ccd64bafa03057f136a78554",
        "doc_id": "9bf33ce0392a43bd89b40fcb4674a4a2",
        "viewer_id": "1fdf44c801094655a327df95fc893cb2",
        "ip": "172.93.12.18",
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML,  like Gecko) Chrome/79.0.3945.117 Safari/537.36",
        "hostname": "172.93.12.18",
        "created_at": "2020-01-14 20:02:24",
        "updated_at": "2020-01-14 21:06:45"
      }
    ]
  }
]

Events

Events are a mixture of initial, keep alive, and user events that occur through the duration of a session. You can read more about event types and data captured here.

List Events

List events associated with session.

GET

/v1/documents/{id}/sessions/{id}/events/

Example Request

$ curl -X GET -H "Accept: application/json" -H "Authorization: Bearer {token}" https://api.vidi.fyi/v1/documents/{id}/sessions/{id}/events/

Example Response

[
  {
    "events": [
      {
        "id": "f04ca01136454744beb958272ca5b328",
        "session_id": "9e324f4a99804bde9affd58a1318f314",
        "type": "viFrame",
        "event":{
          "mouseX": 300,
          "mouseY": -1684,
          "currentPage": 0,
          "currentZoom": 125,
          "pageViewRect": "127,-1417,1137,2846",
          "currentZoomType": "auto"
        },
        "created_at": "2020-01-14 22:44:09",
        "updated_at": "2020-01-14 22:44:09"
      },
      {
        "id": "96c44871f65146c79f11779e300a8b58",
        "session_id": "9e324f4a99804bde9affd58a1318f314",
        "type": "viFrame",
        "event": {
          "mouseX": 1500,
          "mouseY": -1680,
          "currentPage": 0,
          "currentZoom": 125,
          "pageViewRect": "127,-1417,1137,2846",
          "currentZoomType": "auto"
        },
        "created_at": "2020-01-14 22:44:04",
        "updated_at": "2020-01-14 22:44:04"
      }
    ]
  }
]

Retrieve Event

Retrieve metadata associated with event.

GET

/v1/documents/{id}/sessions/{id}/events/{id}/

Example Request

$ curl -X GET -H "Accept: application/json" -H "Authorization: Bearer {token}" https://api.vidi.fyi/v1/documents/{id}/sessions/{id}/events/{id}/

Example Response

[
  {
    "events": [
      {
        "id": "96c44871f65146c79f11779e300a8b58",
        "session_id": "9e324f4a99804bde9affd58a1318f314",
        "type": "viFrame",
        "event": {
          "mouseX": 1343,
          "mouseY": -1680,
          "currentPage": 0,
          "currentZoom": 125,
          "pageViewRect": "127,-1417,1137,2846",
          "currentZoomType": "auto"
        },
        "created_at": "2020-01-14 22:44:04",
        "updated_at": "2020-01-14 22:44:04"
      }
    ]
  }
]

Show examples in:

cURL

Vidi Documentation