Now4real

Enum encompassing all potential error codes in Now4real.

Enum representing subscribable subjects in Now4real.

Configuration object that contains the configured values.

Callback function called when the library has failed to load.

window.now4real = {};
now4real.onerror = function (error) {
  console.log('Now4real failed to load', error.code, error.message)
}

The callback function called when the library is fully loaded, and it is possible to start calling API methods.

Note that the library implements a lazy loading mechanism so that it waits for the visible state of the host page (see Page Visibility API) in order to load.

window.now4real = {};
now4real.onload = function () {
  console.log('Now4real loaded!')
}

A constant string containing the Page Context of the current page. It's configurable through the page_context property of the config object, otherwise it is automatically computed by the library.

The Page Context (combined with the Site Context) allows Now4real to decide whether different users should be considered present on the same page. The term "page" means an actual web page or some logical context (group of pages, virtual place, etc.). This directly impacts page counters, pagechats, rankings, maps, etc.

The default Page Context corresponds to the window.location.pathname, with the following exceptions:

• If the pathname terminates with /index.*, /Index.*, /home.*, /Home.*, /default.* or /Default.*, the Page Context will be truncated to the last "/".
• If the page was loaded from the "file://" protocol, the Page Context will be "/" followed by the name of the file (including any extension).

NOTE: By default, the query string is stripped off and does not contribute to the Page Context. This means, for example, that users on https://example.com/product?id=5&u=123 and https://example.com/product?id=18&u=789 are considered on the same page, thus sharing the same counters and pagechat.

Examples:

Url	Page Context
https://example.com/path/page.html	/path/page.html
https://example.com/path/page.html#hash	/path/page.html
https://example.com/page5?par=val	/page5
https://example.com/page5/	/page5/
http://example.com/path/index.html	/path/
file:///Users/integrator/Desktop/project/app.html	/app.html
http://localhost/project/app.html	/project/app.html

Examples of URLs that point all to the same Page Context:

Url	Page Context
https://example.com/technology/	/technology/
https://example.com/technology/index.html	/technology/
https://example.com/technology/index.htm	/technology/
https://example.com/technology/Home.aspx	/technology/
https://example.com/technology/?id=3	/technology/
https://example.com/technology/index.html?id=4	/technology/

If the page_context property of the config object is used, the behavior of the examples above might be very different. For example, you may include some query parameters, or you may completely remap the actual page path to a different name. Please refer to the documentation of the page_context property for a few examples.

A constant string containing the Site Context of the current page. It is automatically computed by the library and represents the website to which this page pertains. Generally, it corresponds to the window.location.host of the page.

If a hierarchy of domain name aliases and subdomains has been configured in the Now4real Publisher Dashboard, the value may be different from window.location.host: for the top-level site, the configured "master" domain is returned; for a subdomain, the first subdomain name in the subdomain group is returned.

Notice that the protocol ("http://" or "https://") is not considered for the Site Context. The TCP port is considered only if it's not 80 or 443.

The Site Context allows Now4real to decide whether different users are on the same site. This directly impacts site counters, rankings, maps, etc.

As a special case, a sandbox context is available, which allows you to test your Now4real code without mounting it on an actual domain. This context, named "shared-public-sandbox.test" automatically originates in these cases:

• If the page is loaded with the "file://" protocol (from the file system).
• If the hostname is "localhost".
• If the IP address is a loopback address (like 127.0.0.1).

NOTE: the sandbox context is global and is shared among all the users. For example, imagine two developers in two different countries who put the Now4real library in some HTML pages. If they load these pages from the file system or from localhost, they will see each other's presence as if they were on the same site. Any message they post to these pagechats, as well as the page paths and page filenames, will be PUBLIC. This is a handy way to test your code with some real traffic and is also a fun way to meet other developers in real time.

Examples:

Url	Site Context
http://example.com/path/page.html	example.com
https://example.com/path/page2?par=val	example.com
https://www.example.com/path/page3#abc	example.com (if example.com was configured in the Dashboard as the master for example.com and www.example.com domains)
https://example.com:8443/path/page.html	example.com:8443
http://localhost:8080/project/app.html	shared-public-sandbox.test
http://127.0.0.1:8080/project/dev	shared-public-sandbox.test
file:///Users/integrator/Desktop/project/page.html	shared-public-sandbox.test

A constant string representing the version of the library.

// returns "1.0.0"
now4real.version

Method that allows closing the currently open poll in the current Page context.

Once closed, the results will be frozen, and users will no longer be able to vote, although they will still be able to view the results. Optionally, by passing the "remove" parameter as true, you can completely remove the current poll.

The method can only be called by users with the moderator or guest role and only if there is an open poll in the current Page context.

If successful, the "POLL_STATUS" and "POLL" subjects will receive an update with the "closed" field of the poll object set to true. If removed, they will receive null instead. At this point, it is possible to open a new poll again using the createPoll method.

In order for the call to be successful, the client must be connected to the Now4real cloud, and a logged-in Now4real user must be present.

It returns a promise that resolves with an empty object payload or rejects with an instance of Now4realError, specifically one of the following: AbortedError, DisconnectedError, InvalidCallError, NotAuthenticatedError, NotFoundError, ServiceUnavailableError, or TechnicalProblemError.

[Not in Free Plan]

// close the current poll
await now4real.closePoll()

// completely remove the current poll
await now4real.closePoll(true)

Method that allows opening a poll in the current Page context.

Polls enable users to express their preference related to the posed question; they are entirely anonymous and optionally allow multiple-choice answers.

The method can only be called by users with the moderator or guest role, and only if there isn't already another poll open in the same Page context.

In order for the call to be successful, the client must be connected to the Now4real cloud, and a logged-in Now4real user must be present.

If successful, this call will trigger an update for the "POLL_STATUS" and "POLL" subjects, providing information about the newly opened poll.

It returns a promise that resolves with an empty object payload or rejects with an instance of Now4realError, specifically one of the following: AbortedError, AlreadyPresentError, ChatDisabledError, DisconnectedError, InvalidCallError, NotAuthenticatedError, ServiceUnavailableError, or TechnicalProblemError.

[Not in Free Plan]

await now4real.createPoll('What is your favorite music genre?', ['Rock', 'Pop', 'Metal'], { multipleChoice: false })

Method that deletes the message with the passed msgId from the current pagechat.

In order for the call to be successful, the client must be connected to the Now4real cloud, and a logged-in Now4real user must be present.

Each user can only request the deletion of their own messages. Moderators can delete any messages.

It returns a promise that resolves with an empty object payload or rejects with an instance of Now4realError, specifically one of the following: AbortedError, DisconnectedError, InvalidArgumentsError, NotAuthenticatedError, NotAuthorizedError or TechnicalProblemError.

now4real.deleteMessage('MSG_ID_000000042')
.then(_ => {
  console.log('deleteMessage succedeed')
})
.catch(reason => {
  console.log('deleteMessage error', reason.code, reason.message)
})

Method that opens a new browser tab in which the user has the possibility to edit some attributes of their profile, created previously with email signup.

In order for the call to be successful, the client must be connected to the Now4real cloud, and a logged-in Now4real user, by means of email, must be present.

After a successful update of the user profile, all the subjects that contain a reference to that user will receive an update.

It returns a promise that resolves with an empty object payload or rejects with an instance of Now4realError, specifically one of the following: AbortedError, BlockedError, InvalidCallError, or TechnicalProblemError.

now4real.editUserProfile()
.then(_ => {
  console.log('edit popup opened')
})
.catch(reason => {
  console.log('error on opening edit popup', reason.code, reason.message)
})

Method that entirely flush the current pagechat. It can be called only by a logged in Moderator.

If the call is successful, the "LIST_CHAT_MESSAGES" subject will receive a series of "REMOVE" updates which lead to empty the chat.

It returns a promise that resolves with an empty object payload or rejects with an instance of Now4realError, specifically one of the following: AbortedError, DisconnectedError, InvalidCallError, NotAuthenticatedError, ServiceUnavailableError, or TechnicalProblemError.

now4real.flushChat()
.then(_ => {
  console.log('flushChat succeeded')
})
.catch(reason => {
  console.log('flushChat error', reason.code, reason.message)
})

Method that returns the current value of a subscribed subject.
It can be the latest update data object for a counter or a poll-related subject, or the latest snapshot object for the other subjects, such as a ranking or a heatmap. See: CounterUpdate, PollStatusUpdate, PollUpdate, Heatmap, MessageList, Ranking, and TypingList.

The same value can be retrieved as a property access on the Now4real instance.

// returns {value: "1"}
now4real.get(now4real.Subject.COUNTER_PAGE_VIEWERS)

// returns [{ isCurrentPage: true, key: 'example.com/hello.html', title: "example page", url: "http://example.com/hello.html", users: "5" }]
now4real.get(now4real.Subject.RANKING_PAGE_VIEWERS)

// returns {value: "1"}
now4real[now4real.Subject.COUNTER_PAGE_VIEWERS]

Method that gets the configured mute period for the user, if any.

It returns a promise that resolves with a mutePayload or null, depending on the presence of the mute for the user, or rejects with an instance of Now4realError, specifically one of the following: AbortedError, DisconnectedError, InvalidArgumentsError, NotAuthenticatedError, ServiceUnavailableError, or TechnicalProblemError.

now4real.getMute('USER_ID_0000000099')
.then(response => {
  console.log('getMute succeeded', response.expiration)
})
.catch(reason => {
  console.log('getMute error', reason.code, reason.message)
})

Method that allows obtaining the vote of the currently authenticated user in the current poll.

The method can only be called if there is a poll, even if closed, in the current Page context.

In order for the call to be successful, the client must be connected to the Now4real cloud, and a logged-in Now4real user must be present.

It returns a promise that resolves with a getPollVotePayload or rejects with an instance of Now4realError, specifically one of the following: AbortedError, DisconnectedError, InvalidCallError, NotAuthenticatedError, NotFoundError, ServiceUnavailableError, or TechnicalProblemError.

[Not in Free Plan]

// retrieve the vote submitted by the user, indicating their choice for the first option
const { vote } = await now4real.getPollVote()

console.log(vote) // output: [0]

Method that initiates the authentication flow in a new browser tab.
Login is required in order to be able to post messages to the chat.

The specific flow the user will follow depends on how the current site has been configured in the Now4real Dashboard (see the "Authentication" tab in site settings). Please consider that this method doesn't work when "JWT authentication" is selected.

In case of "Social and email login" configuration, the user navigates to a page in which they chooses the authentication provider. This step is perfomed only if the provider parameter is not defined.
If a social provider is chosen, the user proceeds with authentication on the selected social network (if not already signed in) and is prompted to authorize Now4real to access some information on their profile. If the email provider is choosen, the user is taken to a profile creation page in our system (if it doesn't exist), where they can select their preferred email and a custom nickname. The flow is passwordless and involves entering a 6-digit code sent to the chosen email.

In case of "No registration" configuration, the user can simply enter a nickname to join the chat without any registration.

Upon successful authentication, the login information is stored in a localStorage object within our domain. For the "Social and email login" configuration, this information is available to other sites with the same authentication configuration that integrate Now4real and are opened in the same browser. Furthermore, all the browser tabs which have a compatible authentication (including the one that has started the flow) will be notified through a call of the "LOGIN_STATUS" subject callback.

The method returns a promise that resolves with a loginPayload or rejects with an instance of Now4realError, specifically one of the following: AbortedError, AlreadyStartedError, BlockedError, InvalidArgumentsError, InvalidCallError, ServiceUnavailableError, or TechnicalProblemError.

now4real.login('GOOGLE')
.then(response => {
  console.log('login succedeed', response.user)
})
.catch(reason => {
  console.log('login error', reason.code, reason.message)
})

Method that performs a logout of the currently signed in Now4real user from the current browser.

If the call is successful, all the browser tabs (including the one that has requested the logout) will be notified through a call of the "LOGIN_STATUS" subject callback.

It returns a promise that resolves with an empty object payload or rejects with an instance of Now4realError, specifically one of the following: AbortedError, InvalidCallError, ServiceUnavailableError, or TechnicalProblemError.

now4real.logout()
.then(_ => {
  console.log('logout succeeded')
})
.catch(reason => {
  console.log('logout error', reason.code, reason.message)
})

Method that posts the passed message to the current pagechat on behalf of the currently logged in Now4real user.

In order for the call to be successful, the client must be connected to the Now4real cloud, and a logged-in Now4real user must be present.

The maximum allowed message length can be retrieved from the "PARAMETERS" subject, while the minimum interval between two consecutive messages is provided in the response of a successful invocation.

It returns a promise that resolves with a postPayload or rejects with an instance of Now4realError, specifically one of the following: AbortedError, BlockedError, ChatbotError, ChatDisabledError, DisconnectedError, InvalidArgumentsError, NotAuthenticatedError, NotAuthorizedError, ServiceUnavailableError, TechnicalProblemError, TooFrequentError, or UserMutedError.

now4real.post('Hello there!')
.then(_ => {
  console.log('post succedeed')
})
.catch(reason => {
  console.log('post error', reason.code, reason.message)
})

now4real.post('Thanks for the code!!!', { replyTo: 'MSG_ID_000000037' })
.then(_ => {
  console.log('post succedeed')
})
.catch(reason => {
  console.log('post error', reason.code, reason.message)
})

Method that notifies the Now4real cloud that the current logged-in JWT user has accepted Now4real's Terms of Service and Privacy Policy.

This method must be called, in case of custom authentication, before a user sends their first message. Otherwise, any call to the post method would throw an error. A check of the consentGiven attribute of the current user allows you to understand if the user has already provided their consent and therefore there is no need to call this method again.

In order for the call to be successful, the client must be connected to the Now4real cloud, and a logged-in JWT user must be present.

If successful, this call will trigger an update for the 'POLL_STATUS' and 'POLL' subjects, providing information about the newly opened poll.

It returns a promise that resolves with an empty object payload or rejects with an instance of Now4realError, specifically one of the following: AbortedError, DisconnectedError, InvalidCallError, NotAuthenticatedError, ServiceUnavailableError, or TechnicalProblemError.

const currentUser = now4real.LOGIN_STATUS.user

if (!currentUser.consentGiven) {

  // here the user has to explicitly accept Now4real's Terms of Service and Privacy Policy

  // the consent must be stored on the Now4real cloud
  await now4real.registerUserConsent()
}

await now4real.post('Hi!')

Method that requests Now4real reinitialization. Once the reloading process is complete, a call to the onload callback will be re-issued.

It is advisable to call the method only when there are no other calls awaiting resolution. If this happen, the calls would be aborted and their outcome would not be guaranteed.

It can be used to update the launch configuration without the need for a page refresh.

Developers that want to support their SPA sites, offering a different pagechat for each route, can call this method when navigation occurs, to update the Now4real widget context. In this case, the widget must be loaded with a page scope. Remember that, if the SPA is based on hashed URL paths, the page_context parameter needs to be configured and updated accordingly.

// update widget configuration
now4real.config.widget.color_external_background = '#123456'

now4real.reload()

// detect navigation
watch:{
    $route (to, from) {
        now4real.reload()
    }
}

// detect navigation
watch:{
    $route (to, from) {
        now4real.config.page_context = '/chat/' + location.hash
        now4real.reload()
    }
}

Method that allows a user to report a message published by other users on the current pagechat, if he finds any issues with it.

Reports containing these messages will be sent to the email addresses configured in the "User Reporting" section of the Dashboard (according to the configured frequency), who can then decide whether to remove these from the pagechat.

In order for the call to be successful, the client must be connected to the Now4real cloud, and a logged-in Now4real user must be present.

It returns a promise that resolves with an empty object payload or rejects with an instance of Now4realError, specifically one of the following: AbortedError, AlreadyReportedError, DisconnectedError, InvalidArgumentsError, InvalidCallError, NotAuthenticatedError, ServiceUnavailableError, TechnicalProblemError, or UserMutedError.

Method that allows users to submit a vote in the current poll. This can contain a single preference or more, depending on whether the poll is single-choice or multiple-choice.

The method can only be called if there is an open poll in the current Page context.

Upon calling, the "POLL" subject will receive an update containing the updated poll results.

In order for the call to be successful, the client must be connected to the Now4real cloud, and a logged-in Now4real user must be present.

It returns a promise that resolves with an empty object payload or rejects with an instance of Now4realError, specifically one of the following: AbortedError, ClosedError, ChatDisabledError, DisconnectedError, InvalidCallError, NotAuthenticatedError, NotFoundError, ServiceUnavailableError, or TechnicalProblemError.

[Not in Free Plan]

// the user votes for the first answer in the current single-choice poll
await now4real.sendVote([0])

// the user votes all the answers in the current multiple-choice poll
await now4real.sendVote([0, 1, 2])

Method that allows to disable or re-enable the current pagechat. It can be called only by a logged in Moderator.

If the call is successful, the "PARAMETERS" subject will be notified with the updated chatStatus value.

It returns a promise that resolves with an empty object payload or rejects with an instance of Now4realError, specifically one of the following: AbortedError, DisconnectedError, InvalidArgumentsError, InvalidCallError, NotAuthenticatedError, ServiceUnavailableError, or TechnicalProblemError.

now4real.setChatEnabled(false)
.then(_ => {
  console.log('setChatEnabled succeeded')
})
.catch(reason => {
  console.log('setChatEnabled error', reason.code, reason.message)
})

Method that changes the logging level of the library.

It returns a promise that resolves with an empty object payload or rejects with an instance of Now4realError, specifically one of the following: AbortedError, or InvalidArgumentsError.

Method that allows to mute a user in the pagechat for a period of time. The user cannot post any messages until the mute expiration.

In order for the call to be successful, the client must be connected to the Now4real cloud, and a logged-in Now4real Moderator must be present.

It can be called multiple times on the same user, even before the expiration. The mute period will be recomputed and updated at each call.

It returns a promise that resolves with a mutePayload or rejects with an instance of Now4realError, specifically one of the following: AbortedError, DisconnectedError, InvalidArgumentsError, InvalidCallError, NotAuthenticatedError, ServiceUnavailableError, or TechnicalProblemError.

now4real.setMute('USER_ID_0000000099', 60)
.then(response => {
  console.log('setMute succeeded, the user is muted until: ' + new Date(response.expiration).toUTCString())
})
.catch(reason => {
  console.log('setMute error', reason.code, reason.message)
})

Method that notifies the Now4real cloud that the current Now4real user has started typing a message for the current pagechat.

It returns a promise that resolves with an empty object payload or rejects with an instance of Now4realError, specifically one of the following: AbortedError, InvalidCallError, NotAuthorizedError, or TechnicalProblemError.

Method that notifies the Now4real cloud that the current Now4real user has stopped typing a message for the current pagechat.

It returns a promise that resolves with an empty object payload or rejects with an instance of Now4realError, specifically one of the following: AbortedError, InvalidCallError or TechnicalProblemError.

Method that sets a listener for subject updates.
The passed callback function is called each time an update pertaining to the subject has been received from the Now4real cloud with the corresponding instance of Now4realSubjectUpdate.

For some subjects ["COUNTER_PAGE_VIEWERS", "COUNTER_PAGE_CHATTERS", and "COUNTER_CHAT_TYPING"] it is possible to choose a custom Page Context by appending a colon followed by the Page Context just after the subject name. [Not in Free Plan]

Due to performance optimizations, after some time the page is no more visibile (typically because it is gone in the background), the subscribed subjects may no longer receive updates. The normal behavior will be restored when the page becomes visible again.

It returns a promise that resolves with an empty object payload or rejects with an instance of Now4realError, specifically one of the following: AbortedError, InvalidArgumentsError, InvalidCallError, NotAuthorizedError, or TechnicalProblemError.

await now4real.subscribe(now4real.Subject.COUNTER_PAGE_VIEWERS, updObj => {
  console.log('counter update received: ' + updObj.data.value)
})

await now4real.subscribe(`${now4real.Subject.COUNTER_PAGE_VIEWERS}:my-great-path/test.html`, updObj => {
  console.log('counter update received: ' + updObj.data.value)
})

Method that removes a registered listener from a subject.

It returns a promise that resolves with an empty object payload or rejects with an instance of Now4realError, specifically one of the following: AbortedError, InvalidArgumentsError, InvalidCallError, or TechnicalProblemError.

await now4real.unsubscribe(now4real.Subject.COUNTER_PAGE_VIEWERS)

Configuration object to be provided to the API, which contains the configuration settings.

jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyODM3MTI3IiwibmFtZSI6IkphY2sgUGFyayIsInBpY3R1cmUiOiJodHRwczovL2V4YW1wbGUuY29tL2phY2twYXJrLnBuZyJ9.CIrlJRW-6RBVxQ3jArGqeIwkf6xMSUp_4dRGOWFfd-I'
jwt: () => backend.getCurrentUser() // returns a Promise which resolves with the jwt

welcome_message: 'Welcome! _Chat with other visitors in real time._  \nPlease follow our [guidelines](https://example.com/rules).  \nMessages disappear after **{{ time }} {{ timeUnit }}**. ⚡'
welcome_message: '**Welcome!**  \nPlease remember:  \n* Be kind  \n* Stay relevant  \n\n**Enjoy the chat!**'

attention_grabber: 'Chat with the other visitors! ⚡'
attention_grabber: 'There are {{ currentVisitors }} visitors here!'
attention_grabber: 'There are {{ currentVisitorsMinusOne }} other people besides you'

consent_message: 'You should also accept the site\'s [Privacy policy](https://example.com/privacy).'
consent_message: '**Please read** our terms _before continuing_.'

<script type="text/javascript">
  window.now4real = {};
  now4real.config = {
    target: 'api+widget',
    widget: {
      align: 'right',
      align_mobile: 'left',
      color_external_background: '#da3f3f',
      color_external_text: '#ece15d'
    }
  };
  (function () { var n4r = document.createElement('script'); n4r.type = 'text/javascript'; n4r.async = true; n4r.src = 'https://cdn.now4real.com/now4real.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(n4r, s); })();
</script>

<script type="text/javascript">
  // With the now4real.config below, the widget, the API, and the log will be disabled
  // for everyone (even if presence is still silently collected). But setting
  // param_overriding to true allows you to override such behavior for a given browser.
  // To enable the widget on the fly, just call any page of the site once with this
  // query string:
  // https://example.com/?n4rTarget=widget

  // Similarly, to set the log to debug, use this query string:
  // https://example.com/?n4rLogger=debug

  // You can use both the parameters together:
  // https://example.com/?n4rTarget=widget&n4rLogger=debug

  // That browser will remember the new settings for any future visits to any pages of
  // that site. To switch back to the original settings, just call any page of the site
  // once with this query string:
  // https://example.com/?n4rTarget=default&n4rLogger=default

  window.now4real = {};
  now4real.config = {
    target: 'none',
    logger: 'off',
    param_overriding: true
  };
  (function () { var n4r = document.createElement('script'); n4r.type = 'text/javascript'; n4r.async = true; n4r.src = 'https://cdn.now4real.com/now4real.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(n4r, s); })();
</script>

A dictionary object that represents a Heatmap. It has string keys representing the country and number values representing the intensity.

An array that represents the messages available in the current pagechat.

An object that contains the options for the post call.

An array that represents a ranking.

An array that represents the typing list.