Skip to main content

Authentication

buildfire.auth#

Some plugins require the user to be authenticated before continuing on to a particular feature. BuildFire provides easy to use out of the box authentication solution. Log in, register, log out, manage sessions and more.

Methods#

login()
#

buildfire.auth.login(options, callback)

This method will check if the current user is logged in or not. If not, buildfire.js will open the login UI for user to log in or register a new account.

buildfire.auth.login({}, (err, user) => {
console.log(err, user);
});

options#

NameTypeRequiredDescriptionDefault
allowCancelbooleannoA flag to show or hide the cancel link on the login screentrue
showMenubooleannoA flag to show or hide the menu link on the login screentrue

callback(err, user)#

Called when the data is retrieved from the datastore. The callback function is called after login or registration is successful.

NameTypeDescription
errstringerror string, null when operation is successful
userobjectCurrently logged in user containing users public properties
user#

User object with users public properties

NameTypeDescription
_idstringUnique id
createdOnstringDate and time when user profile was created in ISOString format
lastUpdatedstringDate and time when user profile was last updated in ISOString format
emailstringUser's email address
firstNamestringUser's first name
lastNamestringUser's last name
displayNamestringUser's display name
usernamestringUser's username
imageUrlstringUser's profile image url
userProfileobjectObject containing custom user profile public fields
tagsobjectUser's tag object, see more here
oauthProfileobjectCustom object from an OAuth provider if used in login see more here

More Examples#

buildfire.auth.login(
{
allowCancel: false,
showMenu: false,
},
(err, user) => {
console.log(err, user);
}
);

onLogin()
#

buildfire.auth.onLogin(callback, allowMultipleHandlers)

Allows you to pass a listener function that is called whenever the user logs in. Returns an object with clear function that can be used to clear the listener.

buildfire.auth.onLogin((user) => {
console.log(user, "logged in!");
}, true);

callback(user)#

Function that gets called whenever the user logs in.

NameTypeDescription
userobjectCurrently logged in user containing users public properties

allowMultipleHandlers#

NameTypeRequiredDescriptionDefault
allowMultipleHandlersbooleannoTells the method to override all other handlers, or allow multiple handlers to exist at the same time.false

More Examples#

let onLogin = buildfire.auth.onLogin((user) => {
console.log(user, "logged in!");
}, true);
// Clears the listener
onLogin.clear();

logout()
#

buildfire.auth.logout()

Log user out from buildfire.

buildfire.auth.logout();
note

This method does not accept any arguments


onLogout()
#

buildfire.auth.onLogout(callback, allowMultipleHandlers)

Allows you to pass a listener function that is called whenever the user logs out. Returns an object with clear function that can be used to clear the listener.

buildfire.auth.onLogout(() => {
console.log("User logged out!");
}, false);

callback()#

Function that gets called whenever the user logs out.

allowMultipleHandlers#

NameTypeRequiredDescriptionDefault
allowMultipleHandlersbooleannoTells the method to override all other handlers, or allow multiple handlers to exist at the same time.false
let onLogout = buildfire.auth.onLogout(() => {
console.log("User logged out!");
}, false);
// Clears the listener
onLogout.clear();

getCurrentUser()
#

buildfire.auth.getCurrentUser(callback)

Retrieves currently logged in user

buildfire.auth.getCurrentUser((err, user) => {
if (err) return console.error(err);
console.log(user);
});

callback(err, user)#

Called with the current logged in user if exists.

NameTypeDescription
errstringerror string, null when operation is successful
userobjectCurrently logged in user containing users public properties

getUserProfile()
#

buildfire.auth.getUserProfile(options, callback)

Pulls a public profile for a user if you have the userId.

buildfire.auth.getUserProfile({ userId: "USER_ID_HERE" }, (err, user) => {
if (err) return console.error(err);
console.log(user);
});

options#

NameTypeRequiredDescriptionDefault
userIdstringyesThe user id for which to pull a profile

callback(err, user)#

NameTypeDescription
errstringerror string, null when operation is successful
userobjectThe requested user's public properties

user#

NameTypeDescription
userIdstringUser's unique id
displayNamestringUser's display name
firstNamestringUser's first name
lastNamestringUser's last name
usernamestringUser's username
emailstringUser's email
imageUrlstringUser's profile image url
backgroundImagestringUser's profile background-image url
userProfileobjectObject containing custom user's profile public fields
createdOnstringDate and time when user profile was created in ISOString format
lastUpdatedstringDate and time when user profile was last updated in ISOString format

userProfile#

This object contains only public fields.

NameTypeDescription
addressobjectThe address of the user, which would contain fullAddress, geoLocation and customFields which has aptNo and zipCode properties
biostringThe biography of the user
birthDatestringThe birthDate for the user
telstringThe telephone of the user
customTypeFields[object]An array of the user's custom fields' data, where it would contain multiple types of fields (multipleSelect, singleSelect, text and number)

customTypeFields#

NameTypeDescription
idstringExists in all custom fields
typestringExists in all custom fields
valuestring/numberExists in (singleSelect, text and number) fields
values[object]Exists only in multipleSelect field, where it consists of objects as pairs of (value, displayValue)
displayValuestringExists only in singleSelect
note

customTypeFields array can contain multiple fields of the same type; for example, multiple text fields.

note

displayValue represents the display value for applicable fields at the user's creation, or last profile edit; if the display value of a field is changed later in the control panel, it won't be updated until users edit their profiles again.


getUserProfiles()
#

buildfire.auth.getUserProfiles(options, callback)

Same as getUserProfile, but it accepts a list of users.

buildfire.auth.getUserProfiles({ userIds: ["USER_ID_HERE"] }, (err, users) => {
if (err) return console.error(err);
console.log(users);
});

options#

NameTypeRequiredDescriptionDefault
userIdsArrayyesArray of user ids for which to retrieve the profiles

callback(err, users)#

NameTypeDescription
errstringerror string, null when operation is successful
usersobjectArray of user objects
caution

The maximum count of users can be retrieved is 50.


getUserPictureUrl()
#

buildfire.auth.getUserPictureUrl(options)

Returns user picture url by userId or email.

let userPictureUrl = buildfire.auth.getUserPictureUrl({
userId: "USER_ID_HERE",
});

options#

NameTypeRequiredDescriptionDefault
userIdstringrequired if there is no emailUsers unique id
emailstringrequired if there is no userIdUsers email

More Examples#

let userPictureUrl = buildfire.auth.getUserPictureUrl({
email: "email@example.com",
});

openProfile()
#

buildfire.auth.openProfile(userId)

Redirects the app to view user profile page.

let userPictureUrl = buildfire.auth.openProfile("USER_ID_HERE");

userId#

NameTypeRequiredDescriptionDefault
userIdstringyesUsers unique id

More examplses#

Opens profile of currently logged in user

buildfire.auth.getCurrentUser((err, user) => {
if (err) return console.err(err);
if (!user) return console.log("No logged in user");
buildfire.auth.openProfile(user._id);
});

assignUserTags()
#

buildfire.auth.assignUserTags([tags], options, callback)

Assigns a user tag to the currently logged-in user.

buildfire.auth.assignUserTags(["$$vip"], null, (err, result) => {
if (err) {
console.log("Error while adding tags", err);
} else {
console.error("successfully added user tags");
}
});

[tags]#

An array of tag strings to be assigned to currently logged in user. Tags must match the following cirteria:

  • Begin with $$
  • At least 5 character in length including $$
  • May not contain commas (,)
  • Should not contain spaces, spaces will be converted to dashes (-)

options#

Reserved for future usage. can be passed as null.

callback(err, result)#

Called with the current logged in user if exists.

NameTypeDescription
errstringerror string, null when operation is successful
resultbooleantrue when tags are added successfully

keepSessionAlive()
#

buildfire.auth.keepSessionAlive(options, callback)

Resets counting idle time for user sessions. To be used when Session Expiration is enabled on Control Panel and the plugin needs to keep the session alive even if there are no clicks applied to the plugin widget. A good example would be if the user is listening to an audio or watching a video.

buildfire.auth.keepSessionAlive(null, (err, result) => {
console.log(err, result);
});

options#

Reserved for future usage. can be passed as null.

callback(err, user)#

Called with the current logged in user if exists.

NameTypeDescription
errstringerror string, null when operation is successfull
resultbooleantrue when tags are added successfully

searchUsers()
#

buildfire.auth.searchUsers(params, callback)

Searches for app users and returns the result.

buildfire.auth.searchUsers(
{
searchText: 'john',
sort: { createdOn: 1},
limit: 10,
},
(err, result) => {
console.log("Records found: ", result);
}
);

params#

JSON object that contains the searchText, sort column, and pagination parameters.

NameTypeRequiredDescriptionDefault
searchTextstringnoThe target search value (supports searches by displayName, email, firstName, lastName) with consideration for the privacy of each fieldN/A
sortobjectnoObject with properties you'd like to sort by, 1 for ascending and -1 for descending (only supports displayName and createdOn)displayName, createdOn
limitnumbernoNumber of records for this call, the max value is 20.20
skipnumbernoNumber of records to skip. Should be used with a limit.0

callback(err, result)#

Callback function when search is complete

NameTypeDescription
errstringerror string, null when operation is successful
result[object]Array of fetched users