Patrick Kilgore

useXanoAuth Snippet & Documentation

This isn't an official Draftbit API: It's the API of a code snippet we released to help with authentication using the Xano platform.

Overview

This snippet is a custom React Hook code providing functions and values that help you authenticate a user with no code backend dev platform Xano. This is API documentation for that hook, most useful for folks that are comfortable with code. A guided tutorial will be posted soon, watch this space!


Prerequisites

You will need an account on Xano, setup to use email authentication.  Don't forget to enable authentication on any endpoint you want to protect. While this code will work fine without such protections, it will be difficult to test, and, of course, your data will not actually be protected! 

You will also need to configure a Device Variable for your app called AUTH_TOKEN. If you skip this step, you can still protect your app with authentication, but your user's login status will not be saved after they close the app. 

The Snippet:

If you are starting a new app, copy this snippet over the example code in the Components tab of the Custom Code modal. If you already have Components code in your App, you'll have to carefully add the imports separately from the useXanoAuth hook, making sure not to duplicate imports. The "view raw" link below is helpful to copying the whole thing. (direct link)
 


API


Setup

To make useXanoAuth functions available on a screen, you must complete the following steps. 

Add Code Component to Screen

Add a Custom Code Component to the screen.  Set its Custom JSX to:
{ null }
We intend to eliminate this step soon, but it is required for now.

Add Custom Hook call to Screen

Add a new Custom Function to the screen, and select Custom Hook type and customHook (advanced) as its name (or select a any previously created advanced hook). To the end of the body, add:
const XanoAuth = CustomCode.useXanoAuth({
  baseUrl: "YOUR_XANO_ENDPOINT"
});
Replace YOUR_XANO_ENDPOINT with the base request url from Xano's API menu:





Hooks

Before you use any hook, be sure to understand The Rules of Hooks


CustomCode.useXanoAuth()

({ baseUrl: string; }) => 
  ({ login, logout, isAuthenticated, useProtectScreen })

useXanoAuth is itself a React hook. The values, functions, and hooks it returns are documented in this document.

See "Add Custom Hook call to Screen" for an example how to use this hook in a screen.


XanoAuth.useProtectScreen()

({ redirectTo: string; ) => void

useProtectScreen is a hook that will not allow an unauthenticated user to view the screen in which it is used, and instead, will redirect that user to the screen name passed in as the required object containing a redirectTo field.

Note: The name of your screens in Draftbit have all spaces removed, and the word "Screen" appended. For example, if you have a screen named "My app Login" the name you must pass to redirectTo is MyappLoginScreen.

Example use in a Custom Function (Custom Hook (Advanced)): 

 Values


XanoAuth.isAuthenticated

boolean

isAuthenticated is true when an AUTH_TOKEN Device variable was found on the device and its value was anything other than an empty string ("").

Example use in a Custom Function (Custom Hook - Mount Effect) which skips unnecessary logins when used on a login screen:
 

Functions


 XanoAuth.login()

async ({ email: string; password: string; }) => Promise<various>
  - on login failure => never (throws error)

  - on login success => void

login is a function that, when passed an object containing email and password keys will attempt to login with your Xano backend.

Example use in a Custom Function (make sure to check the async toggle!):
 

XanoAuth.logout()

({ redirectTo?: string; }) => void

login is a function will clear the stored AUTH_TOKEN, and, optionally, if passed an object containing a redirectTo string will redirect the user to that screen after clearing the AUTH_TOKEN.

Note: The name of your screens in Draftbit have all spaces removed, and the word "Screen" appended. For example, if you have a screen named "My app Login" the name you must pass to redirectTo is MyappLoginScreen.

Example use in a Custom Function:
 

Settable Global Variables API Documentation

This documentation relates to advanced capabilities of Draftbit. Proceed carefully to avoid breaking your App.

June 1, 2021 Update: This API has been released, and some concepts have been renamed to improve clarity.  Specifically, during beta, "App Variables" were known as "Global Variables" and "Device Variables" were called "Stored Variables".  The documentation below now reflects the current terminology.

Overview

GlobalVariableContext provides the underlying API that Draftbit apps use to set and consume global state in your App. This API is also available within custom code, and is a great way to store global state for your app, like an authentication token. There are two kinds of Global Variables: App Variables and Device Variables.

App Variables

Create App Variables using the App Variables tab of the Settings menu.  An App Variable is a string.  It defaults to a required value, which can be changed with the GlobalVariableContext API while your App is running. However, each time your App is restarted, the App Variable will reset to the default value. If you need to change the default value of an App Variable, you must update the value in the builder and re-publish your App.

Device Variables

Device Variables are a special kind of App Variable that are permanently stored on your users' devices. For example, a user's auth token is usually stored as a Device Variable. Device Variables can only be strings. You can optionally set a default value for a Device Variable (if you do not, it will default to an empty string ""). You can access Device Variables anywhere in your app you use data as a Global Variable, and they can be changed with the GlobalVariableContext Custom Code API while your app is running. However, unlike App Variables, a Device Variable will not reset to the default value the next time the app starts. Rather, it will be the same value it was when the app last closed. Unlike App Variables, re-publishing an app currently has no effect on Device Variables.

Using App and Device Variables in your App

You can use the builder to assign App and Device Variables anywhere variables can be assigned in the builder.  Both show up with the `(global variable)` annotation.


API

You can access the GlobalVariableContext module with React Hooks, when it has been imported.

Setup

You cannot use the GlobalVariableContext API without importing it.

Screens

Draftbit automatically imports GlobalVariableContext on any screens that use a Global Variable, as:
import * as GlobalVariableContext from "../config/GlobalVariableContext";

Custom Code Components

You can import GlobalVariableContext yourself in your Custom Code Components file as:
import * as GlobalVariableContext from "./config/GlobalVariableContext";
We recommend using this exact syntax to avoid the potential for name conflicts with other libraries and future Draftbit features.

Hooks

The GlobalVariableContext API is only available through custom React hooks. Before you use any hook, be sure to understand The Rules of Hooks

GlobalVariableContext.useValues

() => Record<string, string>

useValues is a function that returns an object containing current values of App Variables and Device Variables in your App.

Custom code component example:
 

GlobalVariableContext.useSetValue

() => ({ key: string; value: string; }) => void

useSetValue is a function that returns a setter function that, when called with an object containing key and value fields, will set an App Variable or a Device Variable with the specified key to the specified value.

Custom code component example: 

Like Comment

📱 PWA Install, Auto-update, and Wrapper

We've added two new features to make your Draftbit publications better. 

First, published apps now support offline installation with service workers! This additional PWA support provides a more integrated offline experience on iOS, Android, and desktop (via Chromium Browsers like Google Chrome, Microsoft Edge, and Brave).

As part of this update, we also added support for background updates. If you are using or developing the app in a browser or desktop installation, you will see a small notification when the new version of the app is ready to be installed:

On mobile, any new version will be downloaded in the background the next time you use the app, and installed and available once you close and reopen the app:

Second, when you view a published app on a non-mobile screen, your (usable) app will be wrapped in a phone frame, along with a name, description, and social links to help spread the word about what you've made!


Don't worry! You'll have the same experience as before when viewing the app on mobile screens.
Like Comment

Welcome, feel free to ask questions

I know we have a few new faces taking a look at this feature today, don't be shy we read this channel and are willing to help!
Like Comment