Javascript Events

Events

The Viafoura service publishes several global notifications that can be helpful for developers
who want to run code during different events within our system.

Authentication

Authentication.Login

This event is published when there is a valid login attempt through the Viafoura
login form.

Note that this event only gets published if the Viafoura login form is used.
This event does not indicate whether or not the login was successful.

Examples

window.vf.$subscribe('authentication', 'login', (email, password) => {});

Authentication.Logout

This event is published when there is a logout attempt with the Viafoura
authentication.

Note that this event only gets published if the Viafoura authentication is used.
This event does not indicate whether or not the logout was successful.

Examples

window.vf.$subscribe('authentication', 'logout', () => {});

Authentication.Logout-Failure

This event is published when there is a failed logout attempt with the Viafoura
authentication.

Note that this event only gets published if the Viafoura authentication is used.

Examples

window.vf.$subscribe('authentication', 'logout/failure', () => {});

Authentication.Required

This event is published when the user is unauthenticated (logged out) and attempts to
access an area of the site that requires authentication (eg: logged in comment, or
current user profile).

Examples

// Hook called any time authentication is requested by Viafoura to perform an action
window.vf.$subscribe('authentication', 'needed', () => {
    // Do something here
});

// This event can be published in order to cause the tray to open and display the login
// view. This will not have any effect if Viafoura login is disabled.
window.vf.$publish('authentication', 'needed');

Authentication.Signup

This event is published when there is a signup attempt with the Viafoura
authentication.

Note that this event only gets published if the Viafoura authentication is used.
This event does not indicate whether or not the signup was successful.

Examples

window.vf.$subscribe('authentication', 'signup', () => {});

Authentication.Signup-Failure

This event is published when there is a failed sign up attempt with the Viafoura
authentication.

Note that this event only gets published if the Viafoura authentication is used.

Examples

window.vf.$subscribe('authentication', 'signup/failure', () => {});

Comment

Comment.Created

The event is triggered when a top level comment is successfully created. This event
publishes the comment data for the comment which was created.

Examples

window.vf.$subscribe(
    'comment',
    'created',
    function({
        actor_uuid,
        content,
        content_container_uuid,
        content_uuid,
        parent_actor_uuid,
        parent_uuid,
        section_uuid,
        thread_uuid,
    }) {
        console.log('comment', `The User who commented is: ${actor_uuid}.`);
    });

Comment-Reply

Comment-Reply.Posted

The event when the reply comment is successfully created. This event publishes the
comment data for which the reply was posted.

Examples

window.vf.$subscribe(
    'comment-reply',
    'posted',
    function({
        actor_uuid,
        content,
        content_container_uuid,
        content_uuid,
        parent_actor_uuid,
        parent_uuid,
        section_uuid,
        thread_uuid,
    }) {
        console.log('comment-reply', `The User who replied is: ${actor_uuid}.`);
    });

Commenting

Commenting.Loaded

This event is triggered when the Commenting/Conversations widget is mounted for the
first time. This occurs after the widget has called the API to get the initial set of
comments and has rendered them on the page.

Parameters

el [HTMLElement][1] The DOM element of the Commenting widget

Examples

window.vf.$subscribe('commenting', 'loaded', function(el) {});

Comments

Comments.Read

This event is triggered once per page load when the commenting widget is inside the viewport for 3 seconds (regardless of number of comments present).
The event returns the commenting widget DOM element that was in the viewport.

Examples

window.vf.$subscribe('comments', 'read', function(commentingWidgetEl) {});

Comments.Engage

This event is triggered once per page load when the commenting widget is inside the viewport for 3 seconds and there is at least a single comment visible.
The event returns the commenting widget DOM element that was in the viewport and number of comments visible.

Examples

window.vf.$subscribe('comments', 'engage', function(commentingWidgetEl,commentCount) {});

Comments.Sorted

This event is triggered when the user changes the sort option. The event returns the option selected by the user.

Examples

window.vf.$subscribe('comments', 'sorted', function(sortOptionSelected) {});

Liveblog

Liveblog.Loaded

This event is triggered when the Live Blogging widget is mounted for the first time. This
occurs after the widget has called the API to get the initial set of posts and has
rendered them on the page.

Parameters

el [HTMLElement][1] The DOM element of the Live Blogging widget

Examples

window.vf.$subscribe('liveblog', 'loaded', function(el) {});

Meta

version: 3.0

Livechat

Livechat.Loaded

This event is triggered when the Community Chat widget is mounted for the first time.
This occurs when the widget is rendered on the page before any messages are loaded.

Parameters

el [HTMLElement][1] The DOM element of the Community Chat widget

Examples

window.vf.$subscribe('livechat', 'loaded', function(el) {});

Meta

version: 3.0

Login

Login.Failure

This event is published when a login attempt has failed. This can be caused by a number
of things including the user being banned, network issues, etc. It should be published
with an object containing information about the error and the login.

Examples

window.vf.$subscribe('login', 'failure', function(errorContext, loginContext) {});

Login.Success

This event is published when a login attempt has been successful. It should be published
with an object containing information about the now logged in user.

Examples

window.vf.$subscribe('login', 'success', function(userContext) {});

Logout

Logout.Success

This event is published when a logout attempt is successful.

Examples

window.vf.$subscribe('logout', 'success', function() {});

User-Notifications

User-Notifications.New-Count-Changed

This event is triggered when the number of "new" notifications that a
user has changes.

Parameters

count [Number][2] The current number of new notifications for the current user

Examples

window.vf.$subscribe('user-notifications', 'new-count-changed', (count) => {
    console.log(`The current user has ${count} new notifications`);
});

Profile

Profile.Show

This event is triggered when a user's profile is meant to be shown. It passes the
attributes of the user in question.

Parameters

user VfUser An object defining the user whose profile will be shown

Examples

window.vf.$subscribe('profile', 'show', (user,) => {
    console.log('This is the user whose profile should be shown: ', user);
});

Share.Clicked

The event is triggered when a share button is clicked. The social network that it was
shared to (eg. facebook, twitter) and the button DOM Node which was clicked should both
be published. (Sharebar Only)

Examples

window.vf.$subscribe('share', 'clicked', function(network, button) {});

Share-Total

Share-Total.Loaded

This event is triggered when the Share Total widget is mounted for the first time. (Sharebar Only)

Parameters

el [HTMLElement][1] The DOM element of the Share Total widget

Examples

window.vf.$subscribe('share-total', 'loaded', function(el) {});

Sharebar

Sharebar.Loaded

This event is triggered when the Sharebar widget is mounted for the first time.

Parameters

el [HTMLElement][1] The DOM element of the Sharebar widget

Examples

window.vf.$subscribe('sharebar', 'loaded', function(el) {});

Topics

Topics.Loaded

This event is published when the topics context has been changed. This event is
published with the newest context.

Examples

window.vf.$subscribe('topics', 'loaded', function(topicsContext) {});

Topics.Followed

This event is published when the topics is followed.

Examples

window.vf.$subscribe('topics', 'followed', function(topicsContext) {});

Topics.Unfollowed

This event is published when the topics is unfollowed.

Examples

window.vf.$subscribe('topics', 'unfollowed', function(topicId) {});

Tray

Tray.Close

This event can be used to close the tray.

Examples

window.vf.$publish('tray', 'close');

Tray.Closed

This event is triggered once the tray has been fully closed and is no longer visible to
the user.

Examples

window.vf.$subscribe('tray', 'closed', () => {
    console.log(`You just closed the tray.`);
});

Tray.Open

This event can be used to cause the tray to open when closed.

Parameters

trigger [HTMLElement][1] @deprecated element to focus back to when the tray closes. For example, if you are creating a button to open the tray, this should be a reference to the HTML button causing the tray to open.
tabName [String][3]? can be one of: vf-feed (default), vf-community, vf-settings, vf-account, vf-profile.Note: vf-community and vf-profile will trigger authentication required when the user
is unauthenticated. vf-account will not display when Viafoura login is disabled.

Examples

// Open tray to feed view
window.vf.$publish('tray', 'open');

// Open tray to community view
// in the context of a click event "e"
window.vf.$publish('tray', 'open', e.currentTarget, 'vf-community');

Tray.Opened

This event is triggered once the tray has been newly opened from a closed state and
is fully visible to the user. It passes the currently open view to the callback function.

Examples

window.vf.$subscribe('tray', 'opened', (tabName) => {
    console.log(`You just opened the ${tabName} tab.`);
});

User

User.Loaded

This event is published when the user context has been changed. This event is published
with the newest context.

Examples

window.vf.$subscribe('user', 'loaded', function(userContext) {});

Vf-Ads

Vf-Ads.Request-Comment-Ad

This event is published when an ad slot initially becomes available or is reloaded. Only for Google (Gtag) and Custom Integration.

Parameters

slotName [String][3] The ID of the element that will hold the ad

Examples

window.vf.$subscribe('vf-ads', 'requestCommentAd', function(slotName) {
     const adContainer = document.getElementById(slotName);
     // ... inject your ad into the container
});

Vf-Ads.Request-Liveblog-Ad

This event is published when an ad slot initially becomes available or is reloaded. Only for Google (Gtag) and Custom Integration

Parameters

slotName [String][3] The ID of the element that will hold the ad

Examples

window.vf.$subscribe('vf-ads', 'requestLiveblogAd', function(slotName) {
     const adContainer = document.getElementById(slotName);
     // ... inject your ad into the container
});

Vf-Ads.Request-Content-Recirculation-Ad

This event is published when an ad slot initially becomes available or is reloaded. Only for Google (Gtag) and Custom Integration

Parameters

slotName [String][3] The ID of the element that will hold the ad

Examples

window.vf.$subscribe('vf-ads', 'requestContentRecirculationAd', function(slotName) {
     const adContainer = document.getElementById(slotName);
     // ... inject your ad into the container
});

Vf-Ads.Request-Standalone-Ad

This event is published when an ad slot initially becomes available or is reloaded.

Parameters

slotName [String][3] The ID of the element that will hold the ad

Examples

window.vf.$subscribe('vf-ads', 'requestStandaloneAd', function(slotName) {
     const adContainer = document.getElementById(slotName);
     // ... inject your ad into the container
});

Vf-Ads.Request-Conversation-Starter

This event is published when an ad slot initially becomes available or is reloaded.

Parameters

slotName [String][3] The ID of the element that will hold the ad

Examples

window.vf.$subscribe('vf-ads', 'requestConversationStarter', function(slotName) {
     const adContainer = document.getElementById(slotName);
     // ... inject your ad into the container
});

Vf-Tray

Vf-Tray.Loaded

This event is triggered when the Tray widget is mounted for the first time.

Parameters

el [HTMLElement][1] The DOM element of the Tray widget

Examples

window.vf.$subscribe('vf-tray', 'loaded', function(el) {});

Vf-Tray-Trigger

Vf-Tray-Trigger.Clicked

This event is published when the user has caused the tray to open.

Examples

window.vf.$subscribe('vf-tray-trigger', 'clicked', function() {});

Vf-Tray-Trigger.Loaded

This event is triggered when the Tray Trigger is mounted for the first time.

Parameters

el [HTMLElement][1] The DOM element of the Tray Trigger

Examples

window.vf.$subscribe('vf-tray-trigger', 'loaded', function(el) {});

Widgets

Widgets.Mount

This event can be used to cause the widget mounted code to run.

This can be helpful when you are dynamically adding widgets to the page and want to
force the script to mount them.

Examples

window.vf.$publish('widgets', 'mount', function() {});

Sending Data to Viafoura

In certain cases, yon may need to send some data to Viafoura. This section describes how this can be done for some specific use cases.

Subscription Information

Certain businesses might want to pass user subscription states to Viafoura for attribution and analytics reasons. Depending on use case some or all of the following can be implemented.

Call To Action Click Trough Rate

In order to track impact on call to action click through rate the following needs to be done:

Make sure Viafoura JavaScript code is running on page with call to action (this is usually the page preceding subscription funnel)
Run following JavaScript Code on user click:

window.vf.$publish('analytics', 'interaction', {action:'subscription-cta-click'});

Subscription Funnel Exit Rate

In order to track impact on funnel exit rate the following needs to be done:

Make sure Viafoura JavaScript code is running on funnel/offer landing page (this is usually the very first page in the subscription funnel).
Run following JavaScript Code after page is loaded:

window.vf.$publish('analytics', 'interaction', {
  action:'subscription-entrance',
  uid:'OPTIONAL_LOGGED_IN_HASHED_USER_ID'
});

Subscription Success

In order to send successful subscriptions and be able to attribute subscriptions to Viafoura interactions the following needs to be done:

Make sure that Viafoura JavaScript code is running on subscription confirmation page (i.e. some sort “Thank You” page shown once payment is processed)
Run following JavaScript Code after page load/successful subscription:

window.vf.$publish('analytics', 'interaction', {
  action:'subscription-success',
  uid:'OPTIONAL_LOGGED_IN_HASHED_USER_ID'
});

Note on UID field

Note that uid filed is optional and only needed when top level domain-name of subscription funnel is different from parent site, for example:

when domain is example.com and subscription funnel is on subdomain like subscription.example.com - uid field can be omitted
when domain is example.com and subscription funnel is on subdomain like subscription.example.service.com - uid field is required as then we need to be able to connect subscription to a user and we cannot use cookie value

Do note that uid should match logged in user user identifier passed to Viafoura on login.

Churn Impact

Subscription status of users can degrade over time and users can stop their subscription and revert back to Registered state. To track Viafoura’s impact on churn rate one would need to provide status updates and let Viafoura know when user status changes. The easiest way to do that is to run the following line of code when/after user log ins:

window.vf.$publish('analytics', 'interaction', {action:'access-granted', label: 'REPLACE_WITH_TYPE'});

Where REPLACE_WITH_TYPE should be replaced with either:

registered - these are users that do have an account registered on a site
paid - these are users do have a registered account on a site and are paying for some sort of (premium) access to the content

Wall Information

In some cases it would help to see if users encountered a wall of some sort to really be able to assess impact of such experience on comments, especially when it is completely blocking users from interacting with comments.

The beast way to send Viafoura info about wall interaction is to run the following line of code once user encounters a wall:

window.vf.$publish('analytics', 'interaction', {action:'wall-encounter', label: 'REPLACE_WITH_TYPE'. isBlocking: BOOLEAN});

Where label would be either:

registered - the content behind the wall is available to any user that do have an account registered on a site
paid - the content behind the wall is available to users that have a registered account on a site and are paying for some sort of (premium) access to the content

and isBlocking would be Boolean value set to true if paywall blocks view of comments and false if it does not.