Integrating Facebook Accounts

This topic explains how to allow your users to sign up for and log in to your mobile app with their Facebook account. Just add a few parameters in the developer portal and a few lines of code in your mobile app and you will be social-ready!

Configuring Facebook integration

Creating a Facebook application

To get started, you first need to create a Facebook application and get your Facebook app ID and app secret. For the detailed instructions, see the Facebook official documentation.

You need to provide the following information. In the "Valid OAuth redirect URIs," please specify the value that corresponds to the server location you've selected (please put your AppID in ${your-app-id}).

  • Display Name
  • Namespace
  • Category
  • Valid OAuth redirect URIs (After creating the application, add "Facebook Login" in the Production section and select the "Settings")
    • United States: https://${your-app-id}.us.kiiapps.com/api/apps/${your-app-id}/integration/webauth/callback
    • Japan: https://${your-app-id}.jp.kiiapps.com/api/apps/${your-app-id}/integration/webauth/callback
    • Singapore: https://${your-app-id}.sg.kiiapps.com/api/apps/${your-app-id}/integration/webauth/callback
    • Europe: https://${your-app-id}.eu.kiiapps.com/api/apps/${your-app-id}/integration/webauth/callback

Configuring a Kii application

Take the following steps in the developer portal to configure your application by setting your Facebook app ID and app secret.

  1. Click on the "Edit" button in your application console in the developer portal.

  2. Click "SOCIAL NETWORKS".

  3. Click "Facebook" to open the configuration screen for Facebook.

  4. Set your Facebook app ID and app secret in the "Social Network Connector" section.

Logging in with a Facebook account

The following example illustrates how to authenticate a user with their Facebook account:

  • // Set a Facebook access token.
    var options = {
      access_token: __obtained_access_token__
    };
    
    // Authenticate the user to Kii Cloud with the Facebook access token.
    KiiSocialConnect.logIn(KiiSocialNetworkName.FACEBOOK, options, {
      success: function(user, network) {
        // Do something.
      },
      failure: function(user, network, errorString) {
        // Handle the error.
      }
    });
  • // Set a Facebook access token.
    var options = {
      access_token: __obtained_access_token__
    };
    
    // Authenticate the user to Kii Cloud with the Facebook access token.
    KiiSocialConnect.logIn(KiiSocialNetworkName.FACEBOOK, options).then(
      function(params) {
        var user = params[0];
        var network = params[1];
        // Do something.
      }
    ).catch(
      function(error) {
        // Handle the error.
        var errorString = error.message;
        var network = error.network;
      }
    );

The basic steps are as follows.

  1. Get a Facebook access token. For the detailed instructions, see Configuration and implementation example below. You can also see the Facebook official documentation.

  2. Set the Facebook access token to the access_token parameter of options.

  3. Authenticate the user with the logIn() method. The first argument specifies the target social network, KiiSocialNetworkName.FACEBOOK. If the specified Facebook account is new to Kii Cloud, the user is registered before the login.

When a user logs in with a Facebook account that is new to Kii Cloud, Kii Cloud extracts his/her email address from Facebook and checks if there is a Kii account with the same email address. If such an account exists, Kii Cloud will not execute the sign-up process, but it will link the specified Facebook account with this account.

If the login is successful, the user is cached inside the SDK as the current user and you can get the user information with the KiiUser.getCurrentUser() method.

Linking a Kii account to a Facebook account

You can link existing Kii users to their Facebook accounts. Linked users can log in to Kii Cloud via the Facebook authentication.

Here is the sample code for linking a Kii account to a Facebook account. You basically just need to execute the linkCurrentUserWithNetwork() method.

Note that this sample code assumes that your mobile app has obtained a Facebook access token. For getting a Facebook access token, see Configuration and implementation example below. You can also see the Facebook official documentation.

  • // Assume that a user has logged in.
    
    // Set a Facebook access token.
    var options = {
      access_token: __obtained_access_token__
    };
    
    // Link the Facebook account with the currently logged-in Kii user.
    KiiSocialConnect.linkCurrentUserWithNetwork(KiiSocialNetworkName.FACEBOOK, options, {
      success: function(user, network) {
        // Do something.
      },
      failure: function(user, network, errorString) {
        // Handle the error.
      }
    });
  • // Assume that a user has logged in.
    
    // Set a Facebook access token.
    var options = {
      access_token: __obtained_access_token__
    };
    
    // Link the Facebook account with the currently logged-in Kii user.
    KiiSocialConnect.linkCurrentUserWithNetwork(KiiSocialNetworkName.FACEBOOK, options).then(
      function(params) {
        var user = params[0];
        var network = params[1];
        // Do something.
      }
    ).catch(
      function(error) {
        // Handle the error.
        var user = error.target;
        var errorString = error.message;
        var network = error.network;
      }
    );

Unlinking a Kii account from a Facebook account

Here is the sample code for unlinking a Kii account from a Facebook account. You basically just need to execute the unLinkCurrentUserFromNetwork() method.

  • // Assume that a user has logged in.
    
    // Unlink the Facebook account from the currently logged-in Kii user.
    KiiSocialConnect.unLinkCurrentUserFromNetwork(KiiSocialNetworkName.FACEBOOK, {
      success: function(user, network) {
        // Do something.
      },
      failure: function(user, network, errorString) {
        // Handle the error.
      }
    });
  • // Assume that a user has logged in.
    
    // Unlink the Facebook account from the currently logged-in Kii user.
    KiiSocialConnect.unLinkCurrentUserFromNetwork(KiiSocialNetworkName.FACEBOOK).then(
      function(params) {
        var user = params[0];
        var network = params[1];
        // Do something.
      }
    ).catch(
      function(error) {
        // Handle the error.
        var user = error.target;
        var errorString = error.message;
        var network = error.network;
      }
    );

Configuration and implementation example

This section briefly covers the steps for integrating Facebook account.

Getting a Facebook access token is out of the scope of Kii Cloud feature, so the steps covered in this section are just for your reference. These steps confirmed to work as of October 2017. Search general technical information on the Internet for the up-to-date and more detailed steps.

By following the steps below, you will be able to add a Facebook login button on your mobile app and to authenticate a user with his Facebook username and password. Once the user authentication is passed, your mobile app will get the user's Facebook access token. You can then use the token for leveraging Kii Cloud login and user linking functions, which are covered in the previous section of this page.

When checking articles on the Internet, be careful that some of them cover procedures for getting your (i.e., developer's) access token for auto-posting and such. For the integration with the Kii Cloud, you need to get an end user's access token.

Preparing development environment

For integrating with Facebook, you need to present your Web application via a Web server.

You can run a Web server on your local host (http://localhost:XXX/), but you cannot use the Facebook authentication with a file protocol.

Install and configure a Web server if you have not done so yet.

Configuration on Facebook admin screen

The configuration is made in "facebook for developers".

  1. Open facebook for developers on your web browser and login.

  2. Select "Add a New App", or select the existing Facebook app.

  3. Run the Website "Quickstart".

    If you have not selected Website as the platform yet, start the Facebook SDK quickstart on the "Dashboard" screen by clicking the "Choose Platform" button and select "Website" as the platform.

    If you have already selected Website as the platform, select "Settings" - "Basic" and click the "Quick Start" button in the "Website" section.

  4. Enter your website URL.

    We will later implement a sample code as a whole, so we will skip a step for implementing an initialization code.

    Scroll down the screen and enter your website URL in the "Site URL" window. If you are developing on a local host, set the local host like http://localhost:8080/.

  5. You will get the Facebook App ID and App Secret. Set them in the developer portal.

Create a sample app

There is a section named Facebook Login for the Web with the JavaScript SDK in the documentation provided by Facebook for developers.

By copying the "Full Code Example" provided at the bottom of this page, you can implement a login to Facebook. After you copy the example, change the value of appId in the FB.init() method to your Facebook App ID.

Update the statusCheangeCallback() method in the sample code as follows to get a Facebook access token.

function statusChangeCallback(response) {
  // ......
  if (response.status === 'connected') {
    var accessToken = response.authResponse.accessToken;
    // Add Kii Cloud login process here.
  }

You will add the processes for handling Kii Cloud login and user linking in a place where the comment // Add Kii Cloud login process here. is set. You can use the Facebook access token accessToken in the processes.

When you are done with the implementation, open the Web page. A Facebook login screen should pop up. When the login is succeeded, the statusChangeCallback() method should be executed.

The above sample only implements the basic feature for leveraging the access token. See the Facebook document for a complete implementation guide.