Qbix: guide

Getting Started
Client JS
- Q.js
- Events
- Requests
- Pages
- Tools
- Templates
- Patterns
- Sockets
- Interface
Core
- Files
- Config
- Modules
PHP
- Events
- Requests
- Routes
- Output
- Database
- Models
- Scripts
Server JS
- Node.js
- Requests
- Database
- Models
Cordova / PhoneGap
Users
- Accounts
- Contacts
- Voting
- OAuth
Streams
- The Concepts
- Streams
- Messages
- Types
- Access
- Avatars
- Subscriptions
- Invites
- Relations and Search
Assets
- Credits
- Badges
Commonly Used Stuff
Appendices

Inviting Users

You can invite users to a stream, if they are not already participating in it. When they accept the invite, they normally auto-join the stream and start receiving messages in real time, until they leave it.

To allow the user to invite their contacts, show a standard invite dialog on the client:

Q.Streams.invite(
  publisherId, streamName, 
  options, callback
);

Among the options to this function are:

"identifier": If you don't provide an identifier, the user will be prompted to download your app from the store, unless they have already done so. Once in the app, the user will be able to select emails or mobile numbers of people to invite, from their contact list.
"shouldFollowup" After sending an invite successfully, the user is redirected to an sms or email composer where they can follow up on the invitation, and ask the person they've just invited to click the invitation link that will appear. The templates can be customized, and are named:
- Streams/followup/email/subject
- Streams/followup/email/body
- Streams/followup/email/alert
- Streams/followup/mobile
- Streams/followup/mobile/alert

The designers of the Qbix Platform have gone to great lengths in order to make invitations and onboarding as effective as possible. From one-step signup to onboarding hints, the Qbix Platform helps makes it easier for users to get engaged with your app from the get-go.

Delivering Invites

Invites can be delivered in several ways, depending on how you invite a user:

emailing: a unique link is sent to an email address
texting: a unique link texted to a mobile number
printing: added to a batch in order to be printed and mailed

Note that invites are generated and delivered by the Node.js background process which calls Q.Streams.listen(). You must be running this process with Node.js or the invitations won't be sent. Also, make sure you've configured your local/app.json with the SMTP information for email or Twilio credentials for SMS. The user is not given the invitation link that their friends will receive, to prevent them impersonating their friend (or creating tons of accounts in this way).

The "printing" option is usually done when a new community is created, and is typically done by an install script, containing something like this:

$template = "First/invitations/invited.handlebars";
$result = $area->invite(array('newFutureUsers' => 1), array(
  'html' => array($template, 'apartments'),
  'asUserId' => 'First',
  'label' => 'Users/tenants',
  'appUrl' => Q_Uri::url("First/home"),
  'writeLevel' => Streams::$WRITE_LEVEL['post']
));

You then log in as a user with the "$app/admins" role, and visit the following URLs, printing up to 100 invitations at a time:

$baseUrl/Q/Q/plugins/Streams/invitations?batch=apartments
&invitingUserId=First&limit=100&offset=0

Future User Accounts

When you send invites to identifiers (such as an email address or phone number) which aren't associated to users already in the system, the Qbix platform calls Users::futureUser() to create "future" user accounts. which will be claimed when the user accepts the invite. At that time, the identifier will also be marked as verified, similarly to when the user registers their account and then verifies their email or mobile number.

What this means, however, is that a person might end with more than one user account, one for each identifier to which invites were sent. This would happen, for example, if the user signed up with their email address, didn't add their phone number to the account, but then accepted an invite that was sent to that phone number. In the future, we will improve this by providing a way for users to merge two accounts together.

Until a future user account is claimed, it exists essentially as a shadow profile which your app can let some other users add information to. This can make most users' first visit to the site very rich and engage them right away. However, be careful to keep using access control to avoid the kind of scandals Facebook had to face with shadow profiles.

Conferring access levels

Invites can also be used as an opportunity to confer extra "access levels" to certain users. To learn how this works, read about invites and access control.