Usage

The btn.social SDK is available in two formats and has a number of options for maximum compatibility with any application and branding needs.

There is no tradeoff in functionality between the CDN or the npm SDK sources. It’s merely a difference in packaging. However, if you want maximum customizability, you should lean towards the npm package since the CDN (“web”) SDK includes some done-for-you behaviors that cannot be disabled.

Source: CDN

The SDK is available at https://btn.social/v1/web.js and can be sourced by a simple <script> tag. It’s recommended that you use the async or defer attributes to optimize your page load.

<script async src="https://btn.social/v1/web.js"></script>

When loaded, the btnsocial global object is available. All methods described are available on this namespace.

Unlike the npm package, the web SDK immediately invokes listen() to begin intercepting links to the all <a> links that start with the "https://login.btn.social/" URL prefix.

Options

The web SDK is configured through HTML attributes on the <script> element.

data-mode

Type: "redirect" | "popup"
Default: "redirect"

The type of OAuth flow to initiate.

data-width

Type: number
Default: 500

NOTE: Option only applies when data-mode="popup" is in use.

The width, in pixels, for the "popup" dialog.

data-height

Type: number
Default: 600

NOTE: Option only applies when data-mode="popup" is in use.

The height, in pixels, for the "popup" dialog.

data-jsonp

Type: string
Default: undefined

The name of the function to invoke when the SDK is ready.
Important: The function must be available in the global scope.

This option provides a safe way to interact with the btnsocial global. It guarantees that the btnsocial namespace is defined and available for your callback to use.

Example

<script async data-jsonp="myCallback" src="https://btn.social/v1/web.js"></script>
<script defer>
  // Global function that the SDK will call
  // automatically once it has downloaded
  function myCallback() {
    // Guarantees that the `btnsocial` object is defined
    btnsocial.onlogin(function (payload) {
      console.log('login complete!', payload);
    });
  }
</script>

Source: npm

The "btn.social" package is available on the npm registry:

$ npm install btn.social

While intended for use within single-page applications (SPAs), any application may use the npm package.

You may then use it anywhere within your application:

import * as btn from 'btn.social';

Example

Important: When using the npm package, you must call onlogin() before you invoke listen() – if at all.

import * as btn from 'btn.social';

btn.onlogin(function (payload) {
  console.log('login complete!', payload);
});

// Listen to all links matching:
//~> 'a[href^="https://login.btn.social/"]'
let unlisten = btn.listen({
  // Open links in "popup" mode
  redirect: false,
});

// Some time later...
// Detach a[href^="..."] listener
unlisten();

Interfaces

The SDK’s shared interfaces.
All snippets are represented as TypeScript definitions.

Payload

The response payload object for successful logins.

type Payload<U={}> = {
  network: string; // The network provider used
  user?: U; // The user's provider profile; if configured
  token?: string; // The user's provider token; if configured
  type?: string; // The token type; if `token` is configured
}

Options

The popup dialog’s configuration values.

type Options = {
  /**
   * The desired width of the popup window.
   * @default 500
   */
  width?: number;
  /**
   * The desired height of the popup window.
   * @default 600
   */
  height?: number;
  /**
   * The popup window's target name. Supports special `target=""` values.
   * @example "_self", "_blank", "btn.social"
   * @default ""
   */
  name?: string;
}

Unsubscribe

A returned function that you can call to detach or reset an action.

type Unsubscribe = () => void;

Methods

last

Retrieve the most recent Payload, if any.

Ideal for use alongside redirect() usage to obtain the post-waterfall result.

declare function last(): Payload | undefined;

popup

Initiate a login attempt with a popup window.

declare function popup(
  appid: string, // the Application ID
  network: string, // the lowercased OAuth provider name; eg "github" or "google"
  options?: Options, // custom dialog configuration, if any
): Promise<Payload>;

redirect

Initiate a login attempt with a redirect sequence.

declare function redirect(
  appid: string, // the Application ID
  network: string // the lowercased OAuth provider name; eg "github" or "google"
): void;

onlogin

Important: When using the npm package, you must use onlogin() before listen() is called.

Define a Callback that will run when the user successfully logs in.

Returns an Unsubscribe handler, which will deactivate the Callback provided.

You may have more than one Callback active at a time.

type Callback = (payload: Payload) => any;
declare function onlogin(callback: Callback): Unsubscribe;

listen

Note: This method is only available within the npm package!
Important: Unlike the web SDK, the npm package uses popups by default.

Programmatically attach an event listener to all links that match the selector a[href^="https://login.btn.social/"] at the time of invocation.

Returns an Unsubscribe handler, which you may use to detach all listeners that listen() created.

Ideal for single-page applications (SPAs), where chunks of content swap in and out often.

declare function listen(options?: Options & {
  /**
   * Use redirects instead of popup dialogs
   * @default false
   */
  redirect?: boolean;
}): Unsubscribe;