Weblutions Documentation
Weblutions Main Site Contact Us Our Discord
FaxStore IconFaxStore

Review Booster for Developers

By Josh M. 7 mins 1

This page covers how Review Booster works under the hood: the events it sends and listens for, how a support app can plug into it, its routes, and its database tables. For setting it up, see Review Booster.

Table of Contents


Files

File

Purpose

apps/reviewbooster.js

Entry file: settings, license check, database tables, page injection, app registration

apps/reviewbooster/service.js

Detection and happiness score, the 15 minute check, sending, click and review tracking, coupons, alerts, QR codes, insights

apps/reviewbooster/routes.js

Customer pages and links, staff pages, staff API

apps/reviewbooster/client/

site.js (on-site prompts), staff.js and staff.css (staff pages). The .min files are used unless FaxStore is in developer mode.

apps/configs/web-reviewbooster.json

Settings, edited from Review Booster → Configure

src/views/apps/reviewbooster-*.ejs

public (review, thank-you, support rating and stop pages), insights and configure

Review Booster needs the qr-image npm package, which the App Store installs with it. Its tables are created when FaxStore starts. Nothing is added to installme.sql.


Request Lifecycle

Every prompt is a row in rvb_requests. kind is review (a purchase) or support (a support follow-up).

Status

Meaning

waiting

Not due yet, or due but the customer doesn't qualify yet. dueAt is the next check.

sent

The customer was asked. On-site prompts show for this request.

clicked

The customer clicked a message or prompt.

reviewed

A review was credited to this request (reviewId, reviewChannel, stars).

rated

A support follow-up the customer answered (supportScore, supportComment).

skipped

Closed without asking. skipReason says why.

expired

Closed after waiting too long, or after being asked and not reviewing.

ignored

A purchase that's never asked about (free, added by staff, an excluded product, a duplicate). Left out of insights.

skipReason is one of: account, already-reviewed, refunded, support-contact, support-open, not-downloaded, low-score, opted-out, no-response, staff. For ignored rows it's one of: free, granted, excluded, physical, duplicate, cooldown.

signals stores what the last check found, as JSON: account, optedOut, reviewed, priorPositive, repeat, accountDays, owned, delivered (true, false, or null when there's nothing to download), downloads, refunded, supportContact and supportResolved.


App Events

Review Booster emits these on the faxstore object. Request objects don't include the link token.

Event

Payload

When

reviewbooster:requestSent

{request, channels, step, kind}

A request, reminder (step 1) or support follow-up was sent. channels lists what reached the customer, e.g. ['email', 'discord'], and is empty when only on-site prompts can reach them.

reviewbooster:clicked

{request, channel}

The customer clicked a message or prompt.

reviewbooster:reviewed

{request, reviewId, channel, stars}

A review was credited to a request.

reviewbooster:supportRated

{request, score}

A customer rated their support for the first time.

Reviews posted from Review Booster's own review page also emit core's reviewCreated event, so anything listening for new reviews still works.

faxstore.on('reviewbooster:reviewed', ({request, channel, stars}) => {
    console.log(`${request.productName} got ${stars} stars via ${channel}`);
});

Events Review Booster Listens For

Event

Used for

checkoutReturn

Runs a check a few seconds after a purchase.

reviewCreated

Credits reviews made from the normal review form to a request, or counts them as organic. Sends low rating alerts.

userItemRemoved

Records a refund.

userItemDownloaded

Records a download, alongside downloadLogs.

livechat:started

A support contact (Live Chat app).

livechat:closed

A resolved support contact. When a staff member replied, a support follow-up is created.

support:ticketOpened

A support contact (see below).

support:ticketClosed

A resolved support contact, and a support follow-up.


Connecting a Support System

Any app can feed Review Booster's If they contacted support check and the support follow-up by emitting two events:

// When a customer opens a ticket
faxstore.emit('support:ticketOpened', {userId: '284019384756102938', ticketId: 'T-1042', at: Date.now()});

// When the ticket is closed
faxstore.emit('support:ticketClosed', {userId: '284019384756102938', ticketId: 'T-1042', at: Date.now()});

userId is the customer's users.userId. at is optional and defaults to now. Closing a ticket creates a support follow-up (with source support and sourceRef set to the ticket ID) unless the customer had one in the last few days.


Using Review Booster from Another App

const booster = faxstore.apps.get('review-booster');
if(booster) {
    await booster.api.sweep();                  // run the check now: {at, created, sent, reminders}, or null if unlicensed, off or already running
    const data = await booster.api.insights(30); // the Insights page numbers: 7, 30, 90, 365 or 'all'
}

app.locals.apps['review-booster'] holds {version, state}. state.licensed says whether the license is verified.


Channels

The channel on clicks, reviews and events, and reviewChannel on requests:

Channel

email, discord, notification

Messages

popup, footer, order, downloads

On-site prompts (order covers order and receipt pages)

qr-email

The QR code in a request email

qr:<code>

A QR code or link from QR codes & links

support

A review left after a good support rating

assisted

Asked, but reviewed from the normal review form without clicking

organic

A review from someone who wasn't asked


Routes Reference

All routes have at least two path segments, so they never clash with FaxStore's /:pageName pages.

Method

Path

GET

/reviews/r/:token?c=<channel>&s=<1-5>

Every link in a message or prompt. Counts the click, then opens the review or support page. r=1 marks a reminder.

GET

/reviews/write/:token?s=<1-5>

Review page for one request. Needs the customer to be signed in.

POST

/reviews/write/:token

stars, comment

GET

/reviews/write?ref=<code>

Pick a product to review (QR codes and links).

POST

/reviews/write

product, stars, comment, nonce, ref

GET

/reviews/thanks

Thank-you page after a review

GET

/reviews/support/:token?s=<1-5>

Support rating page. A rating in s is saved by the page's script, not by the GET, so email link scanners can't rate.

POST

/reviews/support/:token

score, comment. Answers JSON when sent with X-Requested-With: rvb.

GET

/reviews/go/:code

A QR code or link. Counts the scan, then opens the product picker.

GET

/reviews/qr/:token.png

A customer's QR code, used in emails

GET, POST

/reviews/stop/:token

Confirm, then stop review requests for that customer

POST

/reviewbooster/api/event

On-site prompt impressions and dismissals. Needs X-Requested-With: rvb.

GET

/reviewbooster/assets/*

Client scripts and styles

Staff pages

Path

/staff/review-booster

Insights. ?tab=requests or ?tab=support, ?range=7|30|90|365|all, ?status=all|waiting|sent|reviewed|closed

/staff/review-booster/configure?tab=<tab>

Settings

/staff/review-booster/qr/<code>.png or .svg

A QR code. ?download=1 to download it.

Staff API

All need the Manage Store permission and X-Requested-With: rvb, and answer JSON.

Method

Path

POST

/staff/review-booster/api/requests/:id/send

Ask now, skipping the checks

POST

/staff/review-booster/api/requests/:id/resend

Ask again

POST

/staff/review-booster/api/requests/:id/skip

Stop asking

POST

/staff/review-booster/api/preview

{kind: 'review'|'support', step: 0|1, fields} → {subject, html}

POST

/staff/review-booster/api/test

Same body. Sends the message to the staff member.

POST

/staff/review-booster/api/sweep

Runs the check now

POST

/backend/review-booster/configure

The settings form


Database Tables

rvb_requests

Column

id

Snowflake ID

token

32 character link token, unique

kind

review or support

userId

users.userId

ownedId, orderId, paymentId

The itemsOwned row, orders row and payment the request is for

productId, productName

source, sourceRef

purchase, livechat or support, and the chat or ticket ID

status, skipReason

See Request Lifecycle

score, signals

Happiness score and what the last check found

purchasedAt, dueAt, sentAt, reminderAt, closedAt, createdAt

Timestamps in milliseconds

step

0, or 1 once the reminder is sent

channelsSent

Comma separated, e.g. email,discord,notification

clicks, firstClickAt, lastClickAt, lastClickChannel

reviewId, reviewChannel, stars

The credited review

supportScore, supportComment

Support follow-ups

couponId, couponCode

The thank-you coupon in promocodes

rvb_events

One row per thing that happened, which the Insights page counts.

Column

id

Auto increment

requestId

The request, when there is one

userId

The customer, when known

channel

See Channels. Support and download events use livechat, support, store or custom.

type

sent, impression, click, review, dismiss, rating, coupon, download, refund, optout, support-contact, support-resolved

meta

The star rating for review and rating, the code for coupon, the itemsOwned ID for download and refund, reminder or support on sent

createdAt

Milliseconds


How Prompts Are Added to Pages

Review Booster wraps res.render and adds its data and site.js before </body>, so themes need no changes. It only does this for signed-in customers who have a request in the sent or clicked status, and never on the staff panel, cart, checkout, login or review pages.

Other apps, like Live Chat, wrap res.render too. Review Booster's wrapper works whichever app loads first, so both apps' additions appear on the page.

The script finds what it needs on each page:

Prompt

Where it goes

Popup, floating badge

Fixed to the corner of the page

Footer badge

The top of the page's <footer>

Order and receipt banner

The top of the first <section> on vieworder and receipt/* pages

Downloads

#s-downloads on the customer's own profile. Review buttons go next to links to /download/latest/<productId>, /releases/<productId> and /download/custom/<ownedId>.

Custom themes that keep these elements get every prompt. If a theme leaves one out, only that prompt is missing.