Looking for the latest build?

Or Import it Directly

<script src="https://unpkg.com/fs-js-lite@latest/dist/FamilySearch.js"></script>
<script type="text/javascript" src="https://sdk.fhtl.byu.edu/FamilySearchX.js"></script>

FamilySearch Made Easy

In recent years, FamilySearch has slimmed down their supported JavaScript SDK to make it a bit lighter on its feet. The Lite JS SDK provided by FamilySearch now handles authentication and provides users with the ability to insert their own endpoints as needed. Although this makes for a much smaller file to load, it also makes it more difficult to use.

The aim of this project is to reduce the amount of legwork required to maintain an application. The FamilySearchX SDK is simply an extension of the Lite JS SDK - adding back certain fundamental calls that are used in almost any interesting application. Although it certainly does not add easy function calls for all of the FamilySearch API, it does cover some of the basics while still allowing users to add their own endpoints and middleware.

Features

  • Perfect superset of the Lite JS SDK
  • Additional calls for getting a person, user, and other components ubiquitous accross most FamilySearch integrations
  • TypeScript support

Support

If you have questions about how to get started with the FamilySearchX SDK, please take a look at our documentation page.

If you can't find the answers you seek there, feel free to email our support team at fhtlab@gmail.com

What is FamilySearchX?

Our friends at FamilySearch have done a pretty good job at providing support for their API, but sometimes we just need a little bit more. FamilySearchX is an "X-tension" of the Lite JS SDK put out by FamilySearch. It's primary purpose is to make it easier for beginners to get started and to help groups with many services (like us) avoid having to make lots of changes throughout their entire app suite as the FamilySearch API evolves.

That said, it's also got all of the raw extensibility of the base SDK, so you can add your own endpoint wrappers as well if you need to.

Environment

Right now, FamilySearchX is designed purely for browsers - not as a node module (yet).

Dependencies

FamilySearchX has only one basic dependencies: the Lite JS SDK (obviously). Here are some basic tags to get the project set up (though you might want to update the versions):

<script src="https://unpkg.com/fs-js-lite@latest/dist/FamilySearch.js"></script>
<script type="text/javascript" src="FamilySearchX.js"></script>

At this point, you are ready to start coding!

Project Structure

We're going to run through basic setup for an app that uses FamilySearchX. This application involves two web pages - one for sign in and the other for the application.

FamilySearchX Initialization

The first step in building an application that uses FamilySearch is to create an instance of FamilySearchX inside of your application. To do this, you will need to build an initialization object. Here is a sample:

var fsxOptions = {
  "environment": "integration",
  "appKey": "aaaaaaaaaaaaaaaaaaaaa",
  "redirectUri": "http%3A%2F%2Fmyurl.com",
  "saveAccessToken": true
}

You can look in the documentation for a better description of what this object needs to look like, but for now, here are some key points:

"environment" refers to what kind of environment you are using. While in development, this will probably stay "integration"

"appKey" plug in your app key here. If you don't have one, you will need to make a FamilySearch Developer account and set up an app.

"redirectUri" Once you are authenticated, FamilySearch will need to know where to redirect the page to. THIS MUST BE URL ENCODED.

"saveAccessToken" usually you will just want this set to true.

As a side note, this object parallels the initialization parameters for the standard FamilySearch class.

Now that you have the initilization options set up, you can use it to instantiate your FamilySearchX module.

var fsx = new FamilySearchX(fsxOptions);

Viola! You've got an instance of FamilySearchX running and you are now ready for sign-in!

Authentication

FamilySearch uses oauth2 to run their sign-in. If you don't know much about oauth, it might be worth looking at. For our purposes, we're going to simplify things down a bit for a basic explanation.

When you register an application with FamilySearch, they assign you an app key. You will use this app key to sign in. Sign in has several phases, but there are two that are important to us.

Asking for an Authentication Token

To start authentication, you will want to make a call like this from your authentication page:

let state = [fsxOptions.redirectUri];
fsx.oauthRedirect(state);

This will start the process off with FamilySearch. The page should change to be their sign-in page. Enter your FamilySearch Developer Integration Credentials - which can be found on the account page of the FamilySearch developer website.

After you sign in, your browser will automatically go to the page listed in your redirect URI - if you did it right.

If you didn't do it right, you may get an error page or it might even just hang. You should read the following:

  • Except for the URL encoding, does your redirect URI match one of the redirect URI's listed for your application?
  • Does your redirect URI match the URI in your state variable? Both should be URL encoded.
  • What does the error say? It's not always obvious, but sometimes can be used to diagnose the issue.

Assuming you are signed in, we'll move on. If not, I'm extremely sorry, since these bugs can be subtle. :_(

Getting the Authentication Token Back

On the page that you get redirected to, we'll need to complete the oauth dance. We can do that using

function verifyToken(error: any, response: object){
  if(!!error){
   console.error("Could not obtain auth token.");
  }
  else{
   console.log("Verifying Auth Token:", response);
   // Application code
  }
};

if(!fsx.oauthResponse(verifyToken)){
  window.location.href="/";
}

In this case, fsx.oauthResponse() is used to simply complete the dance to get you an access token that can be used to get information from FamilySearch. It takes a callback function that will be invoked at the end of the dance.

In addition to the callback, you may get some early feedback as to whether or not the access token made it through. If it doesn't you'll have to handle that, since it means that FamilySearch didn't approve your use of their application. In the code above, we simply redirect to whatever our homepage is.

A simple way to make things work on your main application page is as follows:

function verifyToken(error: any, response: object){
  if(!!error){
   console.error("Could not obtain auth token.");
  }
  else{
   runApplication();
  }
};

function runApplication(){
  // Application code
}

var state = ["http%3A%2F%2Flocalhost%3A9000"];
if(fsx.getAccessToken()){
  runApplication();
}
else if(!fsx.oauthResponse(verifyToken)){
  window.location.href="/";
}

Summary

In the end, you should end up with two pages with scripts that look like this:

AUTHENTICATION SCRIPT
var fsxOptions = {
  "environment": "integration",
  "appKey": "aaaaaaaaaaaaaaaaaaaaa",
  "redirectUri": "http%3A%2F%2Fapplicationpage.com",
  "saveAccessToken": true
}
var fsx = new FamilySearchX(fsxOptions);
let state = [fsxOptions.redirectUri];
fsx.oauthRedirect(state);
APPLICATION SCRIPT
var fsxOptions = {
  "environment": "integration",
  "appKey": "aaaaaaaaaaaaaaaaaaaaa",
  "redirectUri": "http%3A%2F%2Fapplicationpage.com",
  "saveAccessToken": true
}

var fsx = new FamilySearchX(fsxOptions);
function verifyToken(error: any, response: object){
  if(!!error){
   console.error("Could not obtain auth token.");
  }
  else{
   runApplication();
  }
};

function runApplication(){
  // Application code
}

var state = ["http%3A%2F%2Flocalhost%3A9000"];
if(fsx.getAccessToken()){
  runApplication();
}
else if(!fsx.oauthResponse(verifyToken)){
  window.location.href="/";
}

You should be ready to go now. You can look at the documentation page for more information on various calls that are available.





These types and classes are defined in both FamilySearch.d.ts and FamilySearchX.d.ts

The following are public data members of FamilySearchX

The following functions are defined on FamilySearchX

Ready for a Demo?

This demo is pretty simple. Let's start by signing in.

You can use your integration account credentials with this service.