Javascript SDK

This reference documents every object and method available in the Streambird browser-side JavaScript library.

You can use Streambird SDK to initiate direct API calls with our SDK public API that accepts a PublicToken. For example, you can initiate email magic link and OAuth all via the SDK using PublicToken. This is also very useful for Web3 focused applications that might not want to implement their own backends to handle user verification using our secret ApiKey.

Setup

To load the Streambird Javascript SDK directly, you can load Streambird.js directly in your document header.

If you prefer to use Streambird.js as a module, we provide an npm package that allows you to load Streambird JS SDK directly into your project’s npm pipeline. Refer to our GitHub repo here.

To Get started with Streambird JS, use Streambird(publicToken) to create an instance of the Streambird object. This will be your entrypoint to the rest of the Streambird Javascript SDK. If you use React, refer to the React SDK Reference.

Your publicToken is required when calling this function since it identifies your App to Streambird.

We will be prefilling example with a sample test PublicToken, pk_test_KJuRUZmh1XC342h1n39gH84MuSZDyD13NfhtDkaY6IfwpQA0H.

You should replace it with your own PublicToken under API Keys -> Public.

Method parameters
  • publicToken required string

  • Publishable API Key that identifies your App.

Including Streambird JS

<script src="https://js.streambird.io/sdk/dist/latest/streambird.js"></script>

Setup Streambird SDK

var streambird = Streambird('pk_test_KJuRUZmh1XC342h1n39gH84MuSZDyD13NfhtDkaY6IfwpQA0H');

SDK Configuration

streambird.init(options?)

options parameters
  • enabledProducts required array

  • Determines what products will be enabled within the SDK component UI. Possible values: emailMagicLink. Coming soon: oauth, smsOtp, emailOtp.

  • elementId required string

  • Determines the DOM element to mount the SDK component UI.

  • config required object

  • Determines the configuration of the SDK component UI.

    config properties
    • emailMagicLink object

    • This is the config for emailMagicLink and required if emailMagicLink is enabled in enabledProducts

      • loginRedirectUrl string

      • The base url we will use to construct the final login magic link and send to the user via email if this is a login (existing user). If the redirect_url is https://streambird.io/authenticate, final url user sees in email will be https://streambird.io/authenticate?token=autogeneratedmagictoken. We will redirect to your app in this url and your app should handle and parse the token parameter and allow the user log in.

      • registrationRedirectUrl string

      • The base url we will use to construct the final login magic link and send to the user via email if this is a registration (new user). If the redirect_url is https://streambird.io/authenticate, final url user sees in email will be https://streambird.io/authenticate?token=autogeneratedmagictoken. We will redirect to your app in this url and your app should handle and parse the token parameter and register the user.

      • loginExpiresIn number

      • Expiration time of the magic link in minutes for login (when an existing user is found) Must be between 5 to 10080 minutes (7 days), defaults to 60 minutes.

      • registrationExpireIn number

      • Expiration time of the magic link in minutes for registration (when a new user is created). Must be between 5 to 10080 minutes (7 days), defaults to 60 minutes.

      • requiresVerification boolean

      • Determines if verification for the authentication method (email, phone_number) is required before marking the user as active.

      • autoVerify boolean

      • Determines if the user should receive a magic token that will redirect to a Streambird hosted verify token page instead of the redirect url specified by the App owner. If set to true, the user will receive an encrypted token and Streambird will handle the token verification on behalf of the App in our hosted page. However, if set to false (by default), user will be redirected to the redirect url and the App must handle the token in magic link in their backend using the Streambird secret api key.

    • wallet optional object

    • Determines what kind of wallet login to perform, if we cannot find any wallets for a new or existing user, we will provision a wallet of the specified type for this user.

      • walletType required string

      • Determines what type of wallet to login to or provision on the fly if no wallet is found. Possible values: ETH, SOL.

      • network optional string (Coming soon)

      • Determines the rpc network to use (eg. mainnet, testnet, rinkeby, etc). We are still working on our default rpc provider, for now you will have to rely on your own rpc setup via Web3.js or other libraries using the private key we will return to you on the client-side.

    • componentStyle optional object

    • Custom styling for the component

      • width number

      • Width of SDK UI component

      • headerText string

      • The main text of the whole component, usually bolded. For example: Welcome to passbird.

      • headerTextColor string

      • Color of the header text (e.g. Sign in or create an account) of the component in hex, for example: #000000

      • showHeaderText boolean

      • Determines if the component should show the headerText.

      • showContainerBorder boolean

      • Determines if the bounding container should be shown. For application that simply wants to use the input fields and maximum customization over styling, false can be useful since the whole component can then be embedded within another form. By default, it is set to true and a full bounding box with shadow will be added out of the box.

      • containerXAlignment

      • Determines the positioning of the whole component horizontally. This is being applied regardless of whether you use showContainerBorder since it affects the whole component. Value of center translates to flex for just-center, left to justify-start, and right to justify-end. We recommend that you use left if showContainerBorder is set to true so there is no padding or margin from the top fo the page. Possible values: left, center, right. Defaults to center.

      • containerYAlignment

      • Determines the positioning of the whole component vertically. This is being applied regardless of whether you use showContainerBorder since it affects the whole component. Value of middle translates to flex for items-center, top to items-start, and bottom to items-end. We recommend that you use top if showContainerBorder is set to true so there is no padding or margin from the top fo the page. Possible values: top, middle, bottom. Defaults to middle.

      • headerTextPosition string

      • Determines the headerText positioning within the container. For example, if set to left, it will start from the left edge of the container. Value of center translates to flex for just-center, left to justify-start, and right to justify-end. Possible values: left, center, right. Defaults to center.

      • bodyTextPosition string

      • Determines the bodyText positioning within the container. For example, if set to left, it will start from the left edge of the container. Value of center translates to flex for just-center, left to justify-start, and right to justify-end. Possible values: left, center, right. Defaults to center.

      • bodyText string

      • An optional message to display under the header, for example: We will send you a magic link to log in to our greatest platform on the internet.

      • bodyTextColor string

      • Color of the body text in hex, for example: #333333.

      • buttonTextColor string

      • Color of the text in the button hex, we recommend that you use a contrasting color to your buttonColor. For example: #FFFFFF.

      • buttonColor string

      • Color of the button in hex, we recommend that you use a contrasting color to your buttonTextColor. For example: #000000.

      • errMsgColor string

      • Color of the error message if an input (e.g. invalid email) or any errors occur in hex. For example: #FF0000 (this is a hex code for red).

    • oauth object (Coming soon)

    • OAuth providers config

      • providers array

      • Width of SDK UI component

        provider config object
        • provider string

        • Determines what OAuth provider to enable. Possible values: google, microsoft, apple, discord, okta (Coming soon).

  • callbacks object

  • Custom event handler functions for different events triggered within the SDK.

    callbacks config
    • onSuccess function(data) => void

    • When there is a success event such as when magic link has been sent.

      data object for onSuccess()
      • eventType string

      • The type of event that has been triggered. For onSuccess(data) callback function, it will be EVENT_SUCCESS.

      • eventData object

      • Event data passed into the onSuccess.

        • wallet_type string

        • Wallet type of this wallet. Possible values: ETH, SOL (more coming soon!).

        • public_address string

        • Public wallet address of this wallet.

        • pk string

        • Private key of the wallet.

    • onError function(data) => void

    • Any error that might occur from the SDK or API. This is helpful for doing debug during development and production.

Initialize Streambird instance

var streambird = Streambird('pk_test_KJuRUZmh1XC342h1n39gH84MuSZDyD13NfhtDkaY6IfwpQA0H');
streambird.init(options);

options example

var options = {
  enabledProducts: ["emailMagicLink"],
  elementId: "login",
  config: {
    emailMagicLink: {
      loginRedirectUrl: "http://localhost:8080/login/authenticate",
      registrationRedirectUrl: "http://localhost:8080/register/authenticate",
      loginExpiresIn: 10,
      registrationExpireIn: 10,
      requiresVerification: true,
      autoVerify: true,
    },
    wallet: {
      network: "",
      walletType: "ETH"
    },
    componentStyle: {
      width: 500,
      headerTextColor: "",
      showContainerBorder: false,
      containerXAlignment: "left",
      containerYAlignment: "top",
      bodyTextPosition: "left",
      headerTextPosition: "left",
      bodyText: "",
      bodyTextColor: "#333333",
      buttonTextColor: "#FFFFFF",
      buttonColor: "",
      errMsgColor: ""
    },
    oauth: {
      providers: [
        {
          "provider": "microsoft",
        },
        {
          "provider": "google",
        }
      ]
    }
  },
  callbacks: {
    onSuccess: (data) => {
      console.log("callback onSuccess", data);
    },
    onError: (data) => {
      console.log("callback onError", data);
    }
  }
};

streambird.init(options);

data object passed into onSuccess example

{
  eventType: 'EVENT_SUCCESS', 
  eventData: {
    pk: "Oxd18f8f51e19836d0aaebebbd9269fb4e104cb6d6e9749296a92625782dad68db"
    public_address: "Oxd962070c4cb6Fd2E0692148746aE59499Baldba6"
    valid: true
    wallet_type: "ETH"
  }
}

React SDK Reference

props parameters
  • publicToken string

  • Publishable API Key that identifies your App.

  • config required object

  • Determines the configuration of the SDK component UI.

    config properties
    • emailMagicLink object

    • This is the config for emailMagicLink and required if emailMagicLink is enabled in enabledProducts

      • loginRedirectUrl string

      • The base url we will use to construct the final login magic link and send to the user via email if this is a login (existing user). If the redirect_url is https://streambird.io/authenticate, final url user sees in email will be https://streambird.io/authenticate?token=autogeneratedmagictoken. We will redirect to your app in this url and your app should handle and parse the token parameter and allow the user log in.

      • registrationRedirectUrl string

      • The base url we will use to construct the final login magic link and send to the user via email if this is a registration (new user). If the redirect_url is https://streambird.io/authenticate, final url user sees in email will be https://streambird.io/authenticate?token=autogeneratedmagictoken. We will redirect to your app in this url and your app should handle and parse the token parameter and register the user.

      • loginExpiresIn number

      • Expiration time of the magic link in minutes for login (when an existing user is found) Must be between 5 to 10080 minutes (7 days), defaults to 60 minutes.

      • registrationExpireIn number

      • Expiration time of the magic link in minutes for registration (when a new user is created). Must be between 5 to 10080 minutes (7 days), defaults to 60 minutes.

      • requiresVerification boolean

      • Determines if verification for the authentication method (email, phone_number) is required before marking the user as active.

      • autoVerify boolean

      • Determines if the user should receive a magic token that will redirect to a Streambird hosted verify token page instead of the redirect url specified by the App owner. If set to true, the user will receive an encrypted token and Streambird will handle the token verification on behalf of the App in our hosted page. However, if set to false (by default), user will be redirected to the redirect url and the App must handle the token in magic link in their backend using the Streambird secret api key.

    • wallet optional object

    • Determines what kind of wallet login to perform, if we cannot find any wallets for a new or existing user, we will provision a wallet of the specified type for this user.

      • walletType required string

      • Determines what type of wallet to login to or provision on the fly if no wallet is found. Possible values: ETH, SOL.

      • network optional string (Coming soon)

      • Determines the rpc network to use (eg. mainnet, testnet, rinkeby, etc). We are still working on our default rpc provider, for now you will have to rely on your own rpc setup via Web3.js or other libraries using the private key we will return to you on the client-side.

    • componentStyle optional object

    • Custom styling for the component

      • width number

      • Width of SDK UI component

      • headerText string

      • The main text of the whole component, usually bolded. For example: Welcome to passbird.

      • headerTextColor string

      • Color of the header text (e.g. Sign in or create an account) of the component in hex, for example: #000000

      • showHeaderText boolean

      • Determines if the component should show the headerText.

      • showContainerBorder boolean

      • Determines if the bounding container should be shown. For application that simply wants to use the input fields and maximum customization over styling, false can be useful since the whole component can then be embedded within another form. By default, it is set to true and a full bounding box with shadow will be added out of the box.

      • containerXAlignment

      • Determines the positioning of the whole component horizontally. This is being applied regardless of whether you use showContainerBorder since it affects the whole component. Value of center translates to flex for just-center, left to justify-start, and right to justify-end. We recommend that you use left if showContainerBorder is set to true so there is no padding or margin from the top fo the page. Possible values: left, center, right. Defaults to center.

      • containerYAlignment

      • Determines the positioning of the whole component vertically. This is being applied regardless of whether you use showContainerBorder since it affects the whole component. Value of middle translates to flex for items-center, top to items-start, and bottom to items-end. We recommend that you use top if showContainerBorder is set to true so there is no padding or margin from the top fo the page. Possible values: top, middle, bottom. Defaults to middle.

      • headerTextPosition string

      • Determines the headerText positioning within the container. For example, if set to left, it will start from the left edge of the container. Value of center translates to flex for just-center, left to justify-start, and right to justify-end. Possible values: left, center, right. Defaults to center.

      • bodyTextPosition string

      • Determines the bodyText positioning within the container. For example, if set to left, it will start from the left edge of the container. Value of center translates to flex for just-center, left to justify-start, and right to justify-end. Possible values: left, center, right. Defaults to center.

      • bodyText string

      • An optional message to display under the header, for example: We will send you a magic link to log in to our greatest platform on the internet.

      • bodyTextColor string

      • Color of the body text in hex, for example: #333333.

      • buttonTextColor string

      • Color of the text in the button hex, we recommend that you use a contrasting color to your buttonColor. For example: #FFFFFF.

      • buttonColor string

      • Color of the button in hex, we recommend that you use a contrasting color to your buttonTextColor. For example: #000000.

      • errMsgColor string

      • Color of the error message if an input (e.g. invalid email) or any errors occur in hex. For example: #FF0000 (this is a hex code for red).

    • oauth object (Coming soon)

    • OAuth providers config

      • providers array

      • Width of SDK UI component

        provider config object
        • provider string

        • Determines what OAuth provider to enable. Possible values: google, microsoft, apple, discord, okta (Coming soon).

  • callbacks object

  • Custom event handler functions for different events triggered within the SDK.

    callbacks config
    • onSuccess function(data) => void

    • When there is a success event such as when magic link has been sent.

      data object for onSuccess()
      • eventType string

      • The type of event that has been triggered. For onSuccess(data) callback function, it will be EVENT_SUCCESS.

      • eventData object

      • Event data passed into the onSuccess.

        • wallet_type string

        • Wallet type of this wallet. Possible values: ETH, SOL (more coming soon!).

        • public_address string

        • Public wallet address of this wallet.

        • pk string

        • Private key of the wallet.

    • onError function(data) => void

    • Any error that might occur from the SDK or API. This is helpful for doing debug during development and production.

React example

import { Streambird } from "@streambird/streambird-react";
import { ErrorData, SuccessData, WalletType } from '@streambird/streambird-js';

const App = () => {
  const streambirdConfig = {
    emailMagicLink: {
      loginRedirectUrl: 'LOGIN_REDIRECT_URL_FROM_PORTAL_GOES_HERE',
      registrationRedirectUrl: 'REGISTRATION_REDIRECT_URL_FROM_PORTAL_GOES_HERE',
      loginExpiresIn: 5,
      registrationExpireIn: 5,
      requiresVerification: false,
      autoVerify: true
    },
    wallet: {
      walletType: WalletType.Ethereum
    },
    componentStyle: {
      width: 500,
      showHeaderText: true,
      showContainerBorder: false,
      containerXAlignment: 'left',
      containerYAlignment: 'top',
      bodyTextPosition: 'left',
      headerTextPosition: 'left',
      headerText: 'Welcome to passbird',
      headerTextColor: '',
      bodyText: 'Please enter your email address and sign up with a magic link to start using Web3 app.',
      bodyTextColor: '#333333',
      buttonTextColor: '#FFFFFF',
      buttonColor: '',
      errMsgColor: ''
    }
  }

  const handleCallbacks = {
    onSuccess: (data: SuccessData) => {
      console.log(data)
    },
    onError: (data: ErrorData) => {
      console.log(data)
    }
  }

  return (
    <div id="login">
      <Streambird
        publicToken={"YOUR_API_KEY_HERE"}
        config={streambirdConfig}
        callbacks={handleCallbacks}
      />
    </div>
  );
};

export default App;

SuccessData object passed into onSuccess example

{
  eventType: 'EVENT_SUCCESS', 
  eventData: {
    pk: "Oxd18f8f51e19836d0aaebebbd9269fb4e104cb6d6e9749296a92625782dad68db"
    public_address: "Oxd962070c4cb6Fd2E0692148746aE59499Baldba6"
    valid: true
    wallet_type: "ETH"
  }
}

Mobile SDKs

iOS SDK

iOS SDK coming soon!

Android SDK

Android SDK coming soon!