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

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.

[
   {
      "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"
   },
   "..."
]
CODE

'*' - 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:

{
   "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":{
         
      }
   }
}, 
CODE

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:

{
   "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"
      }
   }
}
CODE

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:

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

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:

{
   "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"
      }
   }
}
CODE

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:

{
   "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
   }
}
CODE

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:

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

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:

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

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:

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

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:

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

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:

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

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:

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

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:

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

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:

{
   "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"
   }
}
CODE

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:

{
   "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"
   }
}
CODE

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:

{
   "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"
         }
      ]
   }
}
CODE

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:

{
   "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\"]"
   }
}
CODE

screenshot_generated

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

Example:

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

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:

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

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:

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

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:

{
   "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"
   }
} 
CODE

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:

{
   "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"
   }
}
CODE

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:

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

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:

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

video_chat_archiving_started

The event indicates when a user joins a videochat.

“details”

opentok_session_id

Opentok session ID

Example:

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

pause_started

The event contains information when the session pause started.

“details”

client_index

Client index

Example:

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

pause_ended

The event contains information when the session pause ended.

“details”

client_index

Client index

Example:

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

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.

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

Check out our Javascript API reference for more information.

“details”

msg

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