docs_sdk_init.html

<!-- Docs - SDK - init -->
<div class="section">
  <h2><a href="/docs/">Docs</a> : <a href="/docs/sdk/">SDK</a> : init</h2>

  <p><span class="font-semibold">init</span> needs to be the very first thing you call in your web app. It initializes the SDK with your App ID, and it also handles automatic logins when users return to your web app with an active session.</p>

  <pre>
    <code class="language-javascript">
      userbase.init({
        appId: 'YOUR_APP_ID'
      }).then((session) => {
        // SDK initialized successfully
        
        if (session.user) {
          // there is a valid active session
          console.log(session.user.username)
        }
      }).catch((e) => console.error(e))
    </code>
  </pre>

  <h3 id="params">Parameters</h3>

  <ul>
    <li><span class="field">appId</span> [string] - The App ID you received when you created your Userbase app.</li>
    <li><span class="field">sessionLength</span> [number | optional | Unit: hours | Min: 0.084 (5 mins) | Max: 8760 (1 yr) ] - If resuming a session, this is the number of hours the user's session will extend. Defaults to 24.</li>
    <li><span class="field">allowServerSideEncryption</span> [boolean | optional] - If your app is set to use the <span class="field">Server-side</span> encryption mode in your <a href="https://v1.userbase.com/" target="_blank">Admin panel</a>, this value must be set to true.</li>
    <li><span class="field">updateUserHandler</span> [function | optional] - A callback that gets invoked when a user is updated. See the <span class="field">Advanced</span> section below for more details.</li>
  </ul>

  <h3 id="result">Result</h3>

  <ul>
    <li>
      <span class="field">session</span> [object] - Contains information about the last used session.
      <ul>
        <li>
          <span class="field">user</span> [object] - If set, this contains information about the logged in user.
          <ul>
            <li><span class="field">username</span> [string] - The user's username.</li>
            <li><span class="field">userId</span> [string] - The user's unique identifier.</li>
            <li><span class="field">authToken</span> [string] - The user's authentication token that can be used to verify the user is signed in via the <a href="/docs/api/verify-auth-token/">Verify Auth Token</a> endpoint in the <a href="/docs/api/">Userbase Admin API</a>.</li>
            <li><span class="field">creationDate</span> [string] - The date the user was created.</li>
            <li><span class="field">email</span> [string] - The user's email.</li>
            <li><span class="field">profile</span> [object] - The user's profile.</li>
            <li><span class="field">protectedProfile</span> [object] - The user's protected profile set via <a href="/docs/api/update-user/">Update User</a> in the <a href="/docs/api/">Admin API</a>.</li>
            <li><span class="field">paymentsMode</span> [string] - The app's payments mode set in your Admin panel. Can be 'disabled', 'test', or 'prod'.</li>
            <li><span class="field">subscriptionStatus</span> [string] - The user's subscription status. Can be 'active', 'incomplete', 'incomplete_expired', 'past_due', 'canceled', or 'unpaid'. Each status is explained further <a href="https://stripe.com/docs/api/subscriptions/object#subscription_object-status" target="_blank">here</a>.</li>
            <li><span class="field">subscriptionPlanId</span> [string] - The subscription plan the user is subscribed to.</li>
            <li><span class="field">trialExpirationDate</span> [string] - The date the user's trial expires.</li>
            <li><span class="field">cancelSubscriptionAt</span> [string] - The date the user's subscription is set to be canceled.</li>
          </ul>
        </li>
        <li><span class="field">lastUsedUsername</span> [string] - If set, this is the username of the last user that was logged in.</li>
      </ul>
    </li>
  </ul>

  <h3 id="advanced">Advanced</h3>

  <ul>
    <li>You can provide an <span class="field">updateUserHandler</span> callback function to listen for when a user gets updated in real-time, either via <a href="/docs/sdk/update-user/">updateUser</a> in the SDK, or <a href="/docs/api/update-user/">Update User</a> in the Admin panel. The function can be used to keep your user's state in sync with the server, like this:
      
      <pre>
        <code class="language-javascript">
          userbase.init({
            appId: 'YOUR_APP_ID',
            updateUserHandler: function ({ user }) {
              // update your application state with the updated user
            }
          })
        </code>
      </pre>
  
      The <span class="field">updateUserHandler</span> callback is invoked with the following:

      <ul>
        <li>
          <span class="field">user</span> [object] - The newly updated user.
          <ul>
            <li><span class="field">username</span> [string] - The user's username.</li>
            <li><span class="field">userId</span> [string] - The user's unique identifier.</li>
            <li><span class="field">authToken</span> [string] - The user's authentication token that can be used to verify the user is signed in via the <a href="/docs/api/verify-auth-token/">Verify Auth Token</a> endpoint in the <a href="/docs/api/">Userbase Admin API</a>.</li>
            <li><span class="field">creationDate</span> [string] - The date the user was created.</li>
            <li><span class="field">email</span> [string] - The user's email.</li>
            <li><span class="field">profile</span> [object] - The user's profile.</li>
            <li><span class="field">protectedProfile</span> [object] - The user's protected profile set via <a href="/docs/api/update-user/">Update User</a> in the <a href="/docs/api/">Admin API</a>.</li>
            <li><span class="field">passwordChanged</span> [boolean] - Indicates if a user's password was changed.</li>
            <li><span class="field">paymentsMode</span> [string] - The app's payments mode set in your Admin panel. Can be 'disabled', 'test', or 'prod'.</li>
            <li><span class="field">subscriptionStatus</span> [string] - The user's subscription status. Can be 'active', 'incomplete', 'incomplete_expired', 'past_due', 'canceled', or 'unpaid'. Each status is explained further <a href="https://stripe.com/docs/api/subscriptions/object#subscription_object-status" target="_blank">here</a>.</li>
            <li><span class="field">subscriptionPlanId</span> [string] - The subscription plan the user is subscribed to.</li>
            <li><span class="field">trialExpirationDate</span> [string] - The date the user's trial expires.</li>
            <li><span class="field">cancelSubscriptionAt</span> [string] - The date the user's subscription is set to be canceled.</li>
          </ul>
        </li>
      </ul>
    </li>
  </ul>

  <h3 id="errors">Errors</h3>

  <ul>
    <li>ParamsMustBeObject</li>
    <li>AppIdMissing</li>
    <li>AppIdAlreadySet</li>
    <li>AppIdMustBeString</li>
    <li>AppIdCannotBeBlank</li>
    <li>AppIdNotValid</li>
    <li>UpdateUserHandlerMustBeFunction</li>
    <li>SessionLengthMustBeNumber</li>
    <li>SessionLengthTooShort</li>
    <li>SessionLengthTooLong</li>
    <li>UserAlreadySignedIn</li>
    <li>ServiceUnavailable</li>
  </ul>

</div>

<hr>