Advanced Customization for Login Form

Configuration Reference

Here's an example of a complete configuration:

var config = {
  // Required Basic Configuration
  ApiKeyID: "<your-API-KEY-ID>",
  Type: "PHONE",
  ContainerID: "cotter-container-login",
  RedirectURL: "https://yourwebsite.com/account/create",
  IdentifierField: "phone",
  OnSuccess: payload => {
    window.localStorage.setItem("session", payload.session);
    window.location.href = "/dashboard";
  }
  OnBegin: async payload => {      
    var userID = await this.getUserIDFromPhone(payload.identifier);
    return {
      userID: userID,
      err: null
    };
  },
  // ---------

  // Change Country Code
  CountryCode: ["+62"], // IT HAS TO BE AN ARRAY

  // Styling
  ButtonBackgroundColor: "#000000",
  ButtonTextColor: "#ffffff",
  ButtonText: "Sign Up Now",
  ErrorColor: "#ff0000",
  
  // Event Name in the Event Response
  EventName: "LOGIN_EMPLOYEE",
  
  // Allow OTP as a fallback method for TrustedDevice
  AllowOTPFallback: true,

  // Skipping RedirectURL and receive event response in OnSuccess
  SkipRedirectURL: true,
  
  // Change the prompt message
  AuthRequestText: {
    title: "Approve this login from your phone",
    subtitle: "A notification is sent to your trusted device to confirm it's you",
    image: "https://yourwebsite.com/image.png",
    titleError: "Something went wrong",
    subtitleError: "We are unable to confirm it's you, please try again",
    imageError: "https://yourwebsite.com/image.png",
    imageSuccess: "https://yourwebsite.com/image.png",
    switchOTPText: "Authenticate with OTP instead"
  },
  
  // Receive error message
  OnError: payload => {
    console.log("ERROR", payload);
  }
};

Description

Field Name	Description	Required
ApiKeyID	your API_KEY_ID	Y
RedirectURL	The backend URL where we will send a JSON obj containing form information and a token	Y
Type	"EMAIL" or "PHONE"	Y
ContainerID	id of the <div> where you want to serve Cotter Form.	Y
OnBegin	A function that will be called before the login process begin. Return UserID and error if applicable. Check the specs for OnBegin below.	Y
SkipRedirectURL	true or false . If set to true, then it will skip sending the JSON obj to the RedirectURL, and instead automatically pass it to OnSuccess.	N
ButtonBackgroundColor	Button background color. Use HEX format (e.g. #000000)	N
ButtonTextColor	Button text color. Use HEX format (e.g. #FFFFFF)	N
ButtonText	Button text. Default is "Sign Up Without Password"	N
ErrorColor	Text color for error messages. Use HEX format (e.g. #FFFFFF)	N
EventName	Tag this authentication event with a name, like WITHDRAWAL to make it easier to segment your event logs.	N
IdentifierField	Field name for the identifier to include in the JSON obj. For example, if you want to include the phone number in the JSON obj under key "phone", then fill in IdentifierField = "phone"	Y
AllowOTPFallback	Allow user to choose to authenticate using OTP (One-Time-Password) instead of Trusted Device if they want.	N
OnSuccess	A function that will be called when the signup process succeed. It's recommended to set your localStorage/cookies here and redirect to your dashboard. Check the specs for OnSuccess below	Y
CountryCode	An Array of country code options for the user	N
AuthRequestText	A dictionary to customize the text in the authentication prompt	N
OnError	A function that will be called if there's an error, and will receive the error message or object	N

RedirectURL

We will send a JSON Object to this backend URL. The JSON Object will have the following format:

{
  "ID": 2397,
  "CreatedAt": "2020-04-01T05:28:12.540127Z",
  "UpdatedAt": "2020-04-01T05:28:16.599833Z",
  "DeletedAt": null,
  "client_user_id": "<YOUR USER ID>",
  "issuer": "<YOUR API KEY ID>",
  "event": "LOGIN_WEB",
  "ip": "123.347.26.236",
  "location": "San Mateo",
  "timestamp": "1585718892",
  "method": "TRUSTED_DEVICE",
  "new": false,
  "approved": true,
  "signature": "reBafVsmpxO7km5jpRQ3xA..."
}

Description:

payload.client_user_id

Contains your user's user_id that you used when registering the user to Cotter. This should be the user_id from your backend.

payload.event

The event tag that you specified. The default value is LOGIN_WEB. You should specify this with a relevant tag, like WITHDRAW ,PAYMENT ,etc. You can specify it using the EventName attribute in the config.

Validate the event response

You should validate the event response to make sure it comes from Cotter's server

Validating Cotter's Event Response

Skip RedirectURL

If you want to handle Cotter's Event Response in a function instead of sending it to your backend redirect_url, you can specify

{
  ...
  SkipRedirectURL: true,
}

When this is true, the JSON payload as specified in RedirectURL section will be passed into your OnSuccess function.

OnBegin

This function will be invoked before the Login process. You are expected to return a user_id at the end of the function. You will receive the following payload as a parameter to your function

Payload passed into your OnBegin function

var payload = {
  identifier: "[phone]",
  identifier_type: "PHONE",
  device_type: "BROWSER",
  device_name: "Chrome ..."
};

1. You can do a check against the identifier here before the form is submitted.

2. You should get the user_id based on the identifier in your backend (or use the identifier if that's what you used). This should be the same as the user id used in the Required Steps.

A. If there is no error:

return {
    userID: "<your-user-id>",
    err: null,
}

B. If there is an error:

return {
    userID: "anything",
    err: "Error message",
}

Example:

 OnBegin: payload => {
  if (payload.identifier != "[phone]") {
    return {
      userID: null,
      err: "Phone Number is not allowed",
    }
  }
  // No error, continue submission
  var userID = this.getUserIDFromPhone(payload.identifier);
  return {
    userID: userID,
    err: null,
  };
},

OnSuccess

This function will be called after the call to RedirectURL is successful. Your function will receive the payload returned from RedirectURL.

It is recommended to set your sessions or cookies here, and then redirect to another page in your website. For example:

OnSuccess: payload => {
  // You can set your own sessions for your website
  window.localStorage.setItem("access_token", payload.access_token);
  window.localStorage.setItem("refresh_token", payload.refresh_token);
  window.location.href = "/dashboard";
};

OnSuccess when SkipRedirectURL is true

When you set SkipRedirectURL: true , OnSuccess will instead receive the JSON Event REsponse that was described in RedirectURL section.

CountryCode

The default value is CountryCode: ["+1"];

If you specify this, you have to use an array even though you only need 1 country code!

ex. with 1 country code

CountryCode: ["+1"];

ex. with 2 country codes

CountryCode: ["+62", "+91"];

Currently, the only available countries are United States, India and Indonesia. Chat us on Intercom if you need other countries, we just need to switch it on.

AllowOTPFallback

If you set this to true, your users will have the option to use OTP to login/authenticate. You should set OTP Fallback as true in your dashboard under Rules.