Audit logs

INTRODUCTION

Audit Log is a feature that companies with strict audit and compliance policies will find useful. You can log almost any event that occurs within the session, from web pages visited to button clicks.

These logs are as good as screen-recordings of sessions (even better when you consider negligible data storage costs).

Security

All the audit logs are saved to the specified location and are not accessible to Surfly - you are in control of your data at all times. If the feature is not enabled, all data is getting erased once the co-browsing session ends.

Standard events that are recorded in the Audit logs do not include any sensitive data.

Any sensitive information can easily be masked using Field/Element Masking.
With element masking you can hide parts of web-pages - such as banking account details or patient health record, or inputs made by a user - like login credentials or personal address.
Elements masked will not be visible to a Follower in the session, and the hidden data will not get recorded in the Audit logs.

Example

Here is a simple example of a session and its corresponding Audit log.

The video is from the Agents’s perspective. In this case Agent is a follower.
The session is initiated by a ‘Customer’, who is unable to locate the ‘Log in’ button on a page.

After the ‘Agent’ joins the session, Customer transfers control to the Agent, who then clicks the Login button. After this, Agent transfers the control back to the Customer to fill in the Login details.

You can see the ‘Username’ is masked from the Agent’s screen using “Element Masking”. Customer enters the login details, submits them and then ends the session. The details are neither seen by Agent, nor do they go in the Audit logs.

You can check is the Audit Log that has been recorded here.

GETTING STARTED

Step 1: Enabling Audit logs

You can enable audit logs via the store_session_logs option.
In Surfly Dashboard, go to Settings → Options → Session Functionality and search for “store_session_logs”.

Alternatively, you can enable this option using our APIs:

Step 2: Store your Audit logs

Apart from this, you will need to specify your S3 bucket details.
To do so, go to Surfly Dashboard, go to Settings → Options → Company Settings and fill in these fields:

S3_endpoint_url
S3_access_key
S3_access_secret

Please ensure the S3 bucket has the following policy actions..

GetBucketLocation
PutObject

And lastly, fill in the S3_log_bucket in Settings → Options → Session Functionality.
You can also choose any other cloud bucket that is Amazon S3 standards compatible.

Instead of a cloud bucket, you can also choose to store audit logs at your own location using a webhook. You can configure the webhook on Surfly Dashboard → Settings → Integration.

At the bottom of the page, click “Add webhook“ button.
In the URL field add your destination endpoint, where you want to store your audit logs. Then select “Type“ session.log.

Alternatively, you can configure the webook via our REST API.

Once setup is complete, audit log file will be generated and stored at the location of your choice at the end of each co-browsing session. You are in control of your data at all times.

AUDIT LOG STRUCTURE

Surfly’s Audit logs are JSON format files, with an array of objects structure. Each of the objects represents 1 specific event at a time.

Every event in the file consists of 4 parts: type, details, session_id* and time.

CODE

[
   {
      "time":"date and time of event",
      "type":"type of event",
      "session_id":"ID of the session",
      "details":"the details specific for this type of event"
   },
   {
      "time":"date and time of event",
      "type":"type of event",
      "session_id":"ID of the session",
      "details":"the details specific for this type of event"
   },
   "..."
]

'*' - in session_created event “session_id“ is nested under details.

AVAILABLE EVENTS

In the next sections you can find the detailed descriptions of all the events with the names and details specific for the particular event.

Events related to the session and participants

session_created

The event that every Surfly session starts with. The only event that contains the session_id parameter inside the “details” section.

	“details”
session_id	ID of the session
start_url	URL where the session starts
ip	IP address of the user who creates the session
created_from	The way the session was created, e.g., “outbound”, “widget” etc.
options	Session options
server_region	Surfly server region
meta	Meta data, if provided

Example:

CODE

{
   "type":"session_created",
   "time":"2022-01-21T09:35:17.581036",
   "details":{
      "session_id":"f50mG8gS5llRCOX3cGKnTajkA",
      "start_url":"http://bing.com/",
      "ip":"::ffff:95.97.8.146",
      "created_from":"outbound",
      "options":{
         "agent_can_end_session":false,
         "agent_can_request_control":true,
         "agent_can_take_control":true,
         "allow_control_switching":true,
         "allow_original_file_download":true,
         "allow_pause":true,
         "blocklist":[
            {
               "pattern":".*example\\.com.*"
            }
         ],
         "block_until_agent_joins":false,
         "..."
      },
      "server_region":"eu-nl",
      "meta":{
         
      }
   }
},

leader_joined

The event indicates the moment when a leader opens a leader’s link. It contains information about the user, like their email and browser that the user used to join the session.

“details”
client_index	Index of the user: always “0” for the leader and “1” and more for followers
“user_params”
avatar	User’s avatar grabbed from Gravatar.com, if provided
email	Email address of the user, if provided
follower_prefix	Title follower is referred to: "Follower"
ip	IP address of the leader
name	Name of the user, if provided
queue_index	Index of the queue, if provided
user_agent	Info about user’s browser
username	Name of the user, if provided

Example:

CODE

{
   "time":"2022-01-21T09:35:18.161544875",
   "session_id":"f50mG8gS5llRCOX3cGKnTajkA",
   "type":"leader_joined",
   "details":{
      "client_index":0,
      "user_params":{
         "avatar":"https://www.gravatar.com/avatar/eebed148d8e8f16d071e588748151950?d=404&s=56",
         "email":"inessa@surfly.com",
         "follower_prefix":"",
         "ip":"::ffff:95.97.8.146",
         "name":"Surfly Test",
         "queue_index":"",
         "user_agent":"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/97.0.4692.71 Safari/537.36",
         "username":"Surfly Test"
      }
   }
}

invitation_sent

The event contains information about the session invites that have been sent via email or sms.

	“details”
invite_by	“sms” or “email”
to	Phone number or email depending on “invite_by” field

Example:

CODE

{
   "time":"2022-01-21T09:35:48.4645764",
   "session_id":"f50mG8gS5llRCOX3cGKnTajkA",
   "type":"invitation_sent",
   "details":{
      "invite_by":"email",
      "to":"test@surfly.com"
   }
}

follower_joined

The event indicates the moment when a follower opens a follower’s link. Event repeats for every follower in a session, with a different “client_index” for each follower.

“details”
client_index	Index of the user: always “0” for the leader and “1” and more for followers
“user_params”
avatar	User’s avatar grabbed from Gravatar, if provided
email	Email address of the user, if provided
follower_prefix	Title follower is referred to: "Follower"
ip	IP address of the follower
name	Name of the user, if provided
queue_index	Index of the queue, if provided
user_agent	Info about user’s browser
username	Name of the user, if provided

Example:

CODE

{
   "time":"2022-01-21T09:36:19.432741282",
   "session_id":"f50mG8gS5llRCOX3cGKnTajkA",
   "type":"follower_joined",
   "details":{
      "client_index":1,
      "user_params":{
         "avatar":"https://www.gravatar.com/avatar/72d0bf2a6f3210565fdf06cd8bdbe3cb?d=404&s=56",
         "email":"test@surfly.com",
         "follower_prefix":"",
         "ip":"::ffff:95.97.8.146",
         "name":"Test",
         "queue_index":"bWoZp0KKntjvCPLAVsbQT3IA",
         "user_agent":"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/97.0.4692.71 Safari/537.36",
         "username":"Test"
      }
   }
}

follower_left

The event indicates the moment when a follower leaves a session. It contains more information about the follower, for example what device the user used to participate in the session.

“details”
avatar	User’s avatar grabbed from Gravatar, if provided
client_index	Index of the user: always “0” for the leader and “1” and more for followers
color	Color of the follower’s annotation tool and avatar (if no Gravatar provided)
country_code	Country code based on ip
deviceType	“Desktop“ or “mobile“
email	Email address of the user, if provided
index	Client index: always “0” for the leader and “1” and more for followers
name	Name of the user, if provided
online	Status of the user at the moment of the event: "online" or "offline"
screenHeight	Screen height in pixels
screenWidth	Screen width in pixels
ua	Info about user’s browser, “user_agent“
webrtcEnabled	Whether videochat was used
“drawingSettings”
color	Annotation/drawing tool color
enabled	Whether enable_drawing option has been on
mode	“Permanent“ or “temporary“ drawing mode
timeout	Amount of time in seconds when an annotation starts disappearing in “temporary“ drawing mode
width	Width of the annotation tool
“user_params“
avatar	User’s avatar grabbed from Gravatar, if provided
email	Email address of the user, if provided
follower_prefix	Title follower is referred to: "Follower"
ip	IP address of the follower
name	Name of the user, if provided
queue_index	Index of the queue, if provided
user_agent	Info about user’s browser
username	Name of the user, if provided

Example:

CODE

{
   "time":"2022-01-21T09:42:03.209678752",
   "session_id":"f50mG8gS5llRCOX3cGKnTajkA",
   "type":"follower_left",
   "details":{
      "avatar":"https://www.gravatar.com/avatar/72d0bf2a6f3210565fdf06cd8bdbe3cb?d=404&s=56",
      "client_index":1,
      "color":"blue",
      "country_code":"NL",
      "deviceType":"desktop",
      "drawingSettings":{
         "color":"default",
         "enabled":false,
         "mode":"temporary",
         "timeout":5,
         "width":15
      },
      "email":"test@surfly.com",
      "index":1,
      "name":"Test",
      "online":true,
      "screenHeight":677,
      "screenWidth":1765,
      "ua":"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/97.0.4692.71 Safari/537.36",
      "user_params":{
         "avatar":"https://www.gravatar.com/avatar/72d0bf2a6f3210565fdf06cd8bdbe3cb?d=404&s=56",
         "email":"test@surfly.com",
         "follower_prefix":"",
         "ip":"::ffff:95.97.8.146",
         "name":"Test",
         "queue_index":"bWoZp0KKntjvCPLAVsbQT3IA",
         "user_agent":"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/97.0.4692.71 Safari/537.36",
         "username":"Test"
      },
      "webrtcEnabled":true
   }
}

session_end

The event that every Surfly session ends with. One of the useful metrics here is session duration.

	“details”
duration	The duration of the session
participants	Number of participants (leader and followers)

Example:

CODE

{
   "type":"session_end",
   "time":"2022-01-21T09:42:11.156199",
   "details":{
      "duration":"0:06:53.574883",
      "participants":2
   }
}

Events related to control switching

control_gained

The event indicates the moment when a user gets control inside a session.

	“details”
"client_index"	Index of the user: always “0” for the leader and “1” and more for followers
"username"	Name of the user, if provided

Example:

CODE

{
   "time":"2022-01-21T09:40:11.22883706",
   "session_id":"f50mG8gS5llRCOX3cGKnTajkA",
   "type":"control_gained",
   "details":{
      "client_index":0,
      "username":"Surfly Test"
   }
}

control_switch

The event indicates the moment when control over a session is switched to a different user.

	“details”
"client_index"	Index of the user: always “0” for the leader and “1” and more for followers
"controller"	The user in control: “leader” or “follower”

Example:

CODE

{
   "time":"2022-01-21T09:40:29.268323917",
   "session_id":"f50mG8gS5llRCOX3cGKnTajkA",
   "type":"control_switch",
   "details":{
      "client_index":1,
      "controller":"follower"
   }
}

control_switch_request

The event indicates the moment when a user requests control over a session.

	“details”
"request_type"	The type of control switch request: “control requested”, “control granted” or “control refused”

Example:

CODE

{
   "time":"2022-02-22T16:14:59.547790164",
   "session_id":"f50e8zrJcoKHRiWoSU0IGD2bGw",
   "type":"control_switch_request",
   "details":{
      "request_type":"control requested"
   }
}

Events related to co-browsed content

relocate_start

The event indicates the moment when a web page is opened inside a session.

	“details”
"url"	The URL of the web page that was opened

Example:

CODE

{
   "time":"2022-01-21T09:35:18.723581484",
   "session_id":"f50mG8gS5llRCOX3cGKnTajkA",
   "type":"relocate_start",
   "details":{
      "url":"https://www.bing.com:443/?toHttps=1&redig=5DFED92F32D84B2B95CA97E8E9838E74"
   }
}

navigate

The event indicates the moment when a new Surfly tab is opened inside a session.

	“details”
"url"	The URL opened in the new tab
"username"	Name of the user, if provided

Example:

CODE

{
   "time":"2022-01-21T09:36:33.830090877",
   "session_id":"f50mG8gS5llRCOX3cGKnTajkA",
   "type":"navigate",
   "details":{
      "url":"http://wikipedia.org",
      "username":"Surfly Test"
   }
}

switch_active_tab

The event indicates the moment when a user switches to a different Surfly tab.

	“details”
"url"	The URL opened in the tab that was activated

Example:

CODE

{
   "time":"2022-01-21T09:38:44.047847047",
   "session_id":"f50mG8gS5llRCOX3cGKnTajkA",
   "type":"switch_active_tab",
   "details":{
      "url":"https://fr.wikipedia.org/wiki/Toshiko_Ueda"
   }
}

click

The event is raised when the user in control clicks on an element inside a session.

	“details”
"xpath"	Xpath of the specific element where the click was detected
"attributes"	The attributes of the element, if known, e.g., “href”, “id”
"node_name"	The name of the node where the click was detected

Example:

CODE

{
   "time":"2022-01-21T09:41:10.886314778",
   "session_id":"f50mG8gS5llRCOX3cGKnTajkA",
   "type":"click",
   "details":{
      "attributes":{
         "class":"forecast--high"
      },
      "node_name":"p",
      "xpath":"/html/body/div[6]/div/section[4]/div/div/div[2]/div/section[3]/div/div/div[2]/ul/li/a/p"
   }
}

input_change

The event is raised for <input>, <select>, and <textarea> elements when an alteration to the element's value is committed by a user.

	“details”
xpath	Xpath of the specific element where the change was detected
"attributes"	The attributes of the element, if known, e.g., “id”, “class”, etc
value	The value of the element, if known
node_name	The name of the node where the change was detected
“parent_form_attributes”	The attributes of the parent element, if known, e.g. “action“, “class“, “id“, etc

Example:

CODE

{
   "time":"2022-01-21T09:41:13.943887335",
   "session_id":"f50mG8gS5llRCOX3cGKnTajkA",
   "type":"input_change",
   "details":{
      "attributes":{
         "name":"scope"
      },
      "node_name":"input",
      "parent_form_attributes":{
         "action":"https://search.bbc.co.uk/search",
         "class":"b-f",
         "id":"orb-search-form",
         "method":"get"
      },
      "value":"all",
      "xpath":"/html/body/header/div/div/div[3]/form/div/input"
   }
}

document_edit

The event is raised when an uploaded file is being edited with Surfly's document editor.

“details”
action	Type of edit action, e.g. "add", "remove"
"annotations"
author	Author of the edit
id	Change id
tool	Tool name, e.g. "AnnotationCreateFreeHand"
type	Tool type, e.g. "FreeHand"

Example:

CODE

{
   "time":"2022-02-21T09:39:04.682133863",
   "session_id":"f50mG8gS5llRCOX3cGKnTajkA",
   "type":"document_edit",
   "details":{
      "action":"add",
      "annotations":[
         {
            "author":"Inessa Li (inessa@surfly.com)",
            "id":"204f7a41-085c-a44c-97f7-914e541f4c42",
            "tool":"AnnotationCreateFreeHand",
            "type":"Free Hand"
         }
      ]
   }
}

submit

The event is raised on a form submission by a user.

	“details”
xpath	Xpath to the specific form that was submitted
node_name	The name of the node of the form that was submitted
"form_data"	The data submitted through the form
"attributes"	The attributes of the form, if known, e.g., “action”, “class”

Example:

CODE

{
   "time":"2022-02-21T09:37:12.661682659",
   "session_id":"f50mG8gS5llRCOX3cGKnTajkA",
   "type":"submit",
   "details":{
      "attributes":{
         "action":"/w/index.php",
         "class":"wvui-typeahead-search__form",
         "id":"searchform"
      },
      "form_data":{
         "search":"",
         "title":"Spécial:Recherche",
         "wprov":"acrw1"
      },
      "node_name":"form",
      "xpath":"//*[@id=\"searchform\"]"
   }
}

screenshot_generated

The event is raised when an automated screenshot has been taken inside a session.

Example:

CODE

{
   "time":"2022-01-17T11:18:54.491262954",
   "session_id":"f50wknEOkaaDQgWDgOw3J9wdwA",
   "type":"screenshot_generated",
   "details":null
}

webrtc_stream_exception

The event is raised when a WebRTC screenshot flow has been disrupted by the user - they might have selected a wrong source for screenshots.

This is specific to Screenshots with webRTC functionality.

	“details”
message	exception message, e.g. “Permission Denied“

Example:

CODE

{
   "time":"2022-02-22T15:52:23.381489885",
   "session_id":"f50V2TDKHzbjTWyZD0iCYLOLUg",
   "type":"webrtc_stream_exception",
   "details":{
      "message":"Permission denied"
   }
}

webrtc_stream_ended_by_user

The event is raised when a WebRTC screenshot flow has been disrupted by the user - they might have prematurely ended the WebRTC stream from which screenshots are made.

This is specific to Screenshots with webRTC functionality.

Example:

CODE

{
    "time":"2022-02-22T15:52:07.102701986",
    "session_id":"f50V2TDKHzbjTWyZD0iCYLOLUg",
    "type":"webrtc_stream_ended_by_user",
    "details":null
},

document_share

The event is raised when a document is shared inside a session.

	“details”
file_name	The name of the file that was shared
url	URL of the shared file

Example:

CODE

{
   "time":"2022-01-21T09:38:44.047738283",
   "session_id":"f50mG8gS5llRCOX3cGKnTajkA",
   "type":"document_share",
   "details":{
      "file_name":"Screenshot_20220220-173133.jpg",
      "url":"https://session50.surfly.com/blob/f50mG8gS5llRCOX3cGKnTajkA/.../Screenshot.jpg"
   }
}

file_download

The event is raised when a document is downloaded inside a session.

	“details”
file_name	The name of the file that was downloaded
user_name	The name of the user who downloaded the file

Example:

CODE

{
   "time":"2022-02-21T09:39:08.955836988",
   "session_id":"f50mG8gS5llRCOX3cGKnTajkA",
   "type":"file_download",
   "details":{
      "file_name":"Screenshot_20220220-173133.jpg.pdf",
      "user_name":"Surfly Test"
   }
}

chat

The event is raised when a chat message is sent inside a session.

	“details”
username	Name of the user, if provided
message	The message that was sent

Example:

CODE

{
   "time":"2022-01-21T09:39:29.528786438",
   "session_id":"f50mG8gS5llRCOX3cGKnTajkA",
   "type":"chat",
   "details":{
      "message":"ok",
      "username":"Test"
   }
}

video_chat_enabled

The event indicates when a user joins a videochat.

	“details”
client_index	Index of the user: always “0” for the leader and “1” and more for followers

Example:

CODE

{
   "time":"2022-01-21T09:37:31.150039967",
   "session_id":"f50mG8gS5llRCOX3cGKnTajkA",
   "type":"video_chat_enabled",
   "details":{
      "client_index":0
   }
}

video_chat_archiving_started

The event indicates when a user joins a videochat.

	“details”
opentok_session_id	Opentok session ID

Example:

CODE

{
   "time":"2022-01-21T09:37:31.150039967",
   "session_id":"f50mG8gS5llRCOX3cGKnTajkA",
   "type":"video_chat_enabled",
   "details":{
      "opentok_session_id":"opentok_foo_123"
   }
}

pause_started

The event contains information when the session pause started.

	“details”
client_index	Client index

Example:

CODE

{
   "time":"2022-01-21T09:39:44.48056932",
   "session_id":"f50mG8gS5llRCOX3cGKnTajkA",
   "type":"pause_started",
   "details":{
      "client_index":0
   }
}

pause_ended

The event contains information when the session pause ended.

	“details”
client_index	Client index

Example:

CODE

{
   "time":"2022-01-21T09:39:44.488274147",
   "session_id":"f50mG8gS5llRCOX3cGKnTajkA",
   "type":"pause_started",
   "details":{
      "client_index":0
   }
}

Custom events

client_log

The event contains custom variables that were saved to the audit logs during a session. To use custom variables, you need to use our JavaScript API.

You can supply any information to audit logs via client_log event.
For example, a simple line of code like below might help you to add specific info to the Audit logs, perhaps about products placed into the shopping cart.

CODE

Session.log({Added item: product_ID +" in the basket with value " + product_value})

Check out our Javascript API reference for more information.

	“details”
msg	The list of variables with values stored during the session: “var0”, “var1” etc.