Customize the Form

Configuration Reference

Here's an example of a complete configuration:

var config = {
// Required Basic Configuration
ApiKeyID: "<your-API-KEY-ID>",
Type: "PHONE", // EMAIL or PHONE
ContainerID: "cotter-container-signup",
RedirectURL: "https://yourwebsite.com/account/create",
SkipRedirectURL: false,
IdentifierField: "phone",
OnSuccess: payload => {
// SET Token Cookie/localstorage here
window.localStorage.setItem("access_token", payload.access_token);
window.localStorage.setItem("refresh_token", payload.refresh_token);
window.location.href = "/signin";
},
โ€‹
// Change Country Code
CountryCode: ["+62"], // IT HAS TO BE AN ARRAY
โ€‹
// Styling
ButtonBackgroundColor: "#000000",
ButtonTextColor: "#ffffff",
ButtonText: "Sign Up Now",
ButtonBorderColor: "#D2D3FF", // don't specify for no border
โ€‹
// Adding fields
AdditionalFields: [
{
label: "Full Name",
name: "name",
placeholder: "Enter your full name"
}
],
โ€‹
// Intercepting before authentication is processed
OnBegin: payload => {
if (payload.identifier != "+12345678910") {
return "Phone Number is not allowed";
}
return null;
}
// Add WhatsApp option to send verification code
// (only for type = PHONE)
// ################################################
// # ๐Ÿ‘ˆPlease read the section about WhatsApp ๐Ÿ‘ˆ #
// # to comply with WhatsApp's Policy #
// ################################################
PhoneChannels: ["SMS", "WHATSAPP"], // default = ["SMS"]
// WhatsApp Button Styling
ButtonWAText: "Continue with",
ButtonWATextSubtitle:
"Tell your customer that you'll be sending the verification code via WhatsApp",
ButtonWABackgroundColor: "#128C7E",
ButtonWABorderColor: "#075E54",
ButtonWATextColor: "#ffffff",
ButtonWALogoColor: "white",
};

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

โ€‹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.

โ€‹

Type

"EMAIL" or "PHONE"

Y

ContainerID

id of the <div> where you want to serve Cotter Form.

Y

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

โ€‹AdditionalFieldsโ€‹

Additional fields that you want to include in the JSON obj. Check the specs for Additional Fields Object below

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

โ€‹OnBeginโ€‹

A function that will be called before the signup process begin. Check the specs for OnBegin below

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

PhoneChannels

An Array of channels to send verification code to your users. Default value is ["SMS"].Available values are SMS and WHATSAPP. For example, to allow both SMS and WhatsApp, specify ["SMS", "WHATSAPP"]

N

RedirectURL

Authentication Flow if you use RedirectURL

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

{
"token": {
"identifier": "+12345678910",
"identifier_type": "PHONE",
"receiver": "<your API_KEY_ID>",
"expire_at": "1582679175", // Unix timestamp
"signature": "7en+KvbLpMkA7Z93K5y3a12tDo2x3n..." //Signature
},
[IdentifierField]: "+12345678910",
โ€‹
// Additional Fields
"field_1": "Value inside field 1",
"field_2": "Value inside field 2",
...
}

Description:

payload.Token

Contains the email or phone number of the user. You should verify the signature to ensure that the request comes from Cotter's server.

payload.IdentifierField

This field name will be the same as what you specify in the config above. For example, if your IdentifierField = "PHONE", you'll get

{
...
"PHONE": "+12345678910",
}

payload.AdditionalFields

The rest will be filled with any additional fields you specify in the config. For example if you add fields for "name" and "address", you'll get:

{
...
"name": "Hello World",
"address": "123 Street",
}

Read how to specify Additional Fields Object below.

Skip RedirectURL

Authentication Flow if you use SkipRedirectURL

If you want to handle Cotter's token 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.

Additional Fields

The additional fields will be used to generate more <input> fields for your users. The format is as following:

var config = {
...
AdditionalFields: [
{
label: "Full Name",
name: "name",
placeholder: "Enter your full name"
},
{
label: "Address",
name: "address",
placeholder: "Enter your address"
},
{
label: "Prefilled Info",
name: "prefilled",
type: "hidden", // type can be "hidden", "text" or "number"
initial_value: "autofill value"
}
],
}

Available types: hidden, text, number

This will be sent to you to the RedirectURL endpoint above as part of the JSON object. For example, with the fields above, you'll get a JSON object like the following.

JSON Object to be sent to RedirectURL:

{
"token": {...},
[IdentifierField]: "+12345678910",
โ€‹
// Additional Fields
"name": "Hello World",
"address": "Street Address",
"prefilled": "autofill value"
...
}

โ€‹

OnBegin

This function will be invoked before the Signup/Login process. You will receive the following payload as a parameter to your function

Payload passed into your OnBegin function

var payload = {
identifier: "+12345678910",
identifier_type: "PHONE",
device_type: "BROWSER",
device_name: "Chrome ..."
};

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

If you include OnBegin key, you have to either return an error string, or return null if you want to continue the authentication process:

A. If you want to continue submission:

return null;

B. If you want to stop submission with an error:

return "Your error message";

Example:

OnBegin: payload => {
if (payload.identifier != "+12345678910") {
return "Phone Number is not allowed";
}
// No error, continue submission
return 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 Payload token 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.