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.
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.
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');
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.
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 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.
onSuccess function(data) => void
When there is a success event such as when magic link has been sent.
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" } }
publicToken string
Publishable API Key that identifies your App.
config required object
Determines the configuration of the SDK component UI.
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 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.
onSuccess function(data) => void
When there is a success event such as when magic link has been sent.
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" } }