SAP Customer Data Cloud Positions

Extensions

Skip to end of metadata
Go to start of metadata

Overview

Extensions complement Gigya’s Webhooks and JavaScript Parameters to provide a powerful extensibility suite. Extensions support secure, server-side, synchronous execution of your code. Extensions enable quickly implementing your custom data validations and restrictions, as well as profile enrichment. 

Using Extensions, you can meet a wide range of business use-cases, such as:

  • Save updated data from a third-party system to a user's profile
  • Prevent a user from registering with an abusive username
  • Prevent a user from registering with a disposable email address
  • Validate that zip codes match country and state provided
  • Send SAP Customer Data Cloud SMS messages via any provider you choose, and customize the message received by users

To use Extensions, host custom functions on your site. Then, specify which Extension Endpoint (Gigya flow) to attach these functions to. 

Your custom code should be hosted on a designated URL, and the Gigya Extension service will send an HTTPS POST request to that URL.

Extensions are currently only supported for full registered user accounts, and not available for use with Lite Accounts.

If you have an SAP logon, you can watch an instructional video about Extensions, here.

Adding a New Extension

After your code is prepared and hosted, set up the extension: 

  1. Open the Extensions page of Gigya's Console.
  2. Click Add
  3. Give the extension a friendly name and select the API to which this extension is attached.

  4. Enter the URL where the extension code is hosted.
  5. Under Advanced, you can customize the following settings: 
    • Timeout: The extension timeout in milliseconds. If not specified, the default is 1000 ms. The acceptable range is 10 - 5000 ms.
    • Fallback policy: Decide what happens in case of a technical error in the Extension execution. The default is to ignore the error, meaning the user flow will not be failed. You can choose FailOnAnyError to fail the user flow on any extension error. While this may cause legitimate flows to fail, it will ensure that no one is bypassing the extension logic. 
  6. Save your changes. 
  7. Activate or deactivate the extension as needed.

Extension Code

Overview

This section explains how the Extension POST requests are structured, and what the service expects to receive in response. The POST requests are done using a JWS. The following sections explain the structure of the JWS, the common payload shared by all extension points, and the specific parameters supported for each of the extension points.

General Notes

  • For all extensions, you can configure the fallout policy: what to do in case of failure to get a valid response from the extension point for the specified timeout period. Choose between ignoring the error and letting the flow continue (e.g., the registration will continue as if the extension point was not declared), or failing all flows. In both cases, errors are logged.
  • Any field that is "null", will not be sent.
  • You can define one extension per each extension type, per site (or site group). 
  • You can use Extensions to return a variety of custom messages to the user, including a different message per language. 
  • You can use the same extension code to run a different scenario per each extension point, so that you need only host one piece of code on one designated URL. See the full code sample below.
  • In site groups, the extension is defined in the parent site, and applies to all sites in the group.

JWS

Gigya's HTTPS post requests are a JSON body that contain a single base-64 encoded jws parameter. 

The JWS is structured of three parts, separated by a period:

  • Header: the algorithm and key ID
  • Payload: the extension request parameters. The payload contains common parameters (see below), and different parameters per each endpoint (see the explanations for each endpoint, below)
  • Signature

In the following manner: 

{
     "jws": "[header].[payload].[signature]"
}

 

Use accounts.getJWTPublicKey to retrieve the public key for JWT validation.

See below for a code sample.

Verifying the JWS

Following is some pseudo-code JavaScript for Node JS used for verifying the JWS. You can use it as a basis for your own verification code: 

var getPem = require('rsa-pem-from-mod-exp');
var crypto = require('crypto');

function verify(jws, n, e){
   var pem = getPem(n, e);

   var signature = jws.split('.')[2];
   var securedInput = jws.split('.', 2).join('.');
   
   var verifier = crypto.createVerify('RSA-SHA256');
   verifier.update(securedInput);
   return verifier.verify(pem, signature, 'base64');
}

 

Sample JWS

Following is a sample of a post request passing the jws parameter: 

POST https://test.gigya.com/register HTTP/1.1
Content-Type: application/json; charset=utf-8
 
{
  "jws": "eyJhbGciOiJSUzI1NiIsImtpZCI6IlJEQXpSRVl5TmpCRk5USTVSak5ETURrd1JEUkJNMEZDUkRRM1FqQkNSRUpDUmpZNE9ESkZRUSJ9.eyJhcGlLZXkiOiIzX096aXd3dy0tLTQ0NDRhM3NVbXhFUUtBcTBxZ1pJZG83OUpTd0VrYm9xa2xQMkRQN2FRblFjTUFzM2VxNXd3d3ciLCJwYXJlbnRBcGlLZXkiOiIzX096aXd3dy0tLTQ0NDRhM3NVbXhFUUtBcTBxZ1pJZG83OUpTd0VrYm9xa2xQMkRQN2FRblFjTUFzM2VxNXd3d3ciLCJjYWxsSUQiOiI0YzkxMDVmMWM3NmI0NmViYjNmMDA3ZWFkZTc3ZGZjZiIsImV4dGVuc2lvblBvaW50IjoiT25CZWZvcmVBY2NvdW50c0xvZ2luIiwiZGF0YSI6e319.zYRS4Y6pjKbQOYqHUuRf_iEY7KkNS6lqPQTHOimzUHF8o5q25V1k2fcO4o8wkLt1Yh5zERvC4d6BUnIAbcrbLhHfhJfAiuT4FuDmzedjgORuVFRUGZh2dFQvpDxbpsJkbJ4aXtE4nJE3FpAFCxh5yRhI5Y0NPUlKDxpxW8omkV4VVur13I-OOcVKIn8iBFgNFQV17lwgc6S3gt5kYiFvlIQ9WfMInnt0ozj0GpFLTKn1wWkeYGNxaOYuHOx7jtaDl_4cEN2fHKPA9_awjyNQQNKMt7jL6wsmFfvIHdaCAX8Qy9zQ-TQW-XBn-pSQOopoYyq0cGVe0Yu44HhyFwrtLg"
}

This translates as follows:
Header: 

{
  "alg": "RS256",
  "kid": "RDAzREYyNjBFNTI5RjNDMDkwRDRBM0FCRDQ3QjBCREJCRjY4ODJFQQ"
}

Payload: 

{
  "apiKey": "3_Oziwww---4444a3sUmxEQKAq0qgZIdo79JSwEkboqklP2DP7aQnQcMAs3eq5wwww",
  "parentApiKey": "3_Oziwww---4444a3sUmxEQKAq0qgZIdo79JSwEkboqklP2DP7aQnQcMAs3eq5wwww",
  "callID": "4c9105f1c76b46ebb3f007eade77dfcf",
  "extensionPoint": "OnBeforeAccountsLogin",
  "data": {}
}

Followed by a signature verification section. 


Common Payload

The shared parameters that are always sent from Gigya when posting to the URL: 

NameTypeDescription
apiKeystringThe API key of the site for which this extension and API are run.
callIDstringThe call ID that is used throughout the flow by the Gigya APIs. The call ID is used for tracking and troubleshooting.
extensionPointstringThe name of the extension point. Acceptable values are: OnBeforeAccountsLogin, OnBeforeAccountsRegister, OnBeforeSetAccountInfo, OnBeforeSocialLogin, OnBeforeSendSMS.
parentApiKeystringIf the site is part of a site group, the API key of the parent site for which this extension and API are run.
dataJSON object

Contains the params and context JSON object, and may contain additional objects or parameters depending upon the extension point being called.

  • params (JSON object): A set of fields related to this user interaction (e.g., registration). These vary between extension points, as elaborated below.
  • context (JSON object): Any additional information passed in the request that is not directly related to the flow. Currently, only the clientIP field is passed.

 

Processing the Response

To retrieve and handle the data from the extensions, you must register the onError event of the method you are using (Screen-Set EventsPlugin Events) and implement logic to handle any errors that are returned, i.e.,

gigya.accounts.showScreenSet({
	"screenSet": "Default-RegistrationLogin",
	"onError": function(e) {
		// do something with the userFacingMessage returned from the extension
		// if (e.userFacingMessage == "my message") {
			// do something
		//}
	}
});
 
// OR //
 
gigya.socialize.showLoginUI({
	"provider":"saml-idp1",
	"onError": function(e) {
		// do something with the userFacingMessage returned from the extension
		// if (e.userFacingMessage == "my message") {
			// do something
		//}
	}
});

Supported Statuses

  • OK - used for validation. Enables the user flow.
  • FAIL - used for validation. Stops the user flow. 
  • ENRICH (currently supported only for the OnBeforeSetAccountInfo extension) - used for data enrichment (see examples below).
  • CONTINUE (currently supported only for the OnBeforeSendSMS extension) - proceed with the Gigya flow (i.e. Gigya should send an SMS to the user).

 

OnBeforeAccountsRegister

This extension point is triggered within the accounts.register API, right after Gigya runs all validation checks that are required for creating the user in the database and right before creating the user. After this point (unless an extension point returns an error indicating Gigya to fail the request), the user will be created. The newly created user may be in a 'Pending Finalization' state (e.g. if a few required fields are missing) and will then need to complete more steps in order to be fully registered. 

The following flow describes the interaction between Gigya and the extension service during a user's registration flow, when the fallback policy is set to ignore all errors. Note that in this case, unless the response returned to Gigya from the extension URL specifically requests to fail the registration, Gigya will proceed with the registration as usual. 

Unique Parameters Sent 

These are the parameters unique to this extension type that you can expect to receive from Gigya, followed by the full structure of the post request. These parameters are sent in addition to the common payload described above.

NameTypeDescription
dataJSON

The data object includes:

PropertyTypeDescription
usernamestringThe unique name the user chose for themselves upon registration. The registration will include either a username or an email.
emailstringThe email provided by the user for registration purposes. The registration will include either a username or an email.
passwordstringThe user's password.
profileJSON objectA Profile Object, containing the user's profile information. 
langstringThe code of the language in which to display content to this user. You can find the supported language codes here.
regSourcestringThe source of the registration. The default value is the site registration page URL, but it can be any string value. 
secretAnswerstringThe user's answer to the secret question, used for verifying the user.
secretQuestionstringThe secret question that may be used for verifying the user. 
dataJSON objectCustom data, stored in the data namespace.
subscriptionsJSON objectA Subscriptions Object, containing subscription data for this user.
preferencesJSON objectA Preferences Object, containing consent data for this user.
contextJSON object

The context object includes:

  • clientIp - The ip address of the client that made the request.
paramsJSON object

The params object includes:

  • email - The user's email address.
  • password - The password the user entered.
  • profile - JSON containing the user's account profile object.
  • data - JSON containing the user's account data object.

 

Payload Sample

Sample onBeforeAccountsRegister Payload
{
  "apiKey": "3_ve...tyu", 
  "callID": "809.....169f", 
  "extensionPoint": "OnBeforeAccountsRegister",
  "data": {
    "params": {
      "email": "test1@test.com",
      "password": "what ever password the user entered",
      "profile": {
        "firstName": "test"
      },
      "data": {
        "terms": true
      }
    },
    "context": {
      "clientIP": "1.0.0.0"
    }
  }
}

 

Extension Response

Gigya expects to receive a response in the following structures from the extension URL.
Response indicating that Gigya should proceed as usual with the registration process:

 

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "status": "OK",
}

 

Response indicating that the registration should be failed:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "status": "FAIL",
  "data": {
     "validationErrors" : [ // Array of up to 50 items, in the following structure:
       {
        "fieldName": string of up to 200 characters containing the name of the field that had an issue
        "message": string of up to 2000 characters containing the custom error message the user will see in regards to this field
      }
    ]
  }
}

 

For example, if the extension validation code decided the registration should be failed:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "status": "FAIL",
  "data": {
    "validationErrors": [ 
      {
        "fieldName": "profile.email",
        "message": "The email should belong to the 'gigya.com' domain"
      },
      {
        "fieldName": "profile.firstName",
        "message": "We consider this word offensive, please use something else"
      },
    ]
  }
}

 

 

OnBeforeAccountsLogin

This extension point is triggered during accounts.login, right after Gigya runs the validation checks that are required for logging the user in. It is triggered in a standard login process, i.e. not in a re-authentication or link accounts scenario.

If two-factor authentication is set up on your site as part of Risk Based Authentication, and a user is asked to perform a second authentication (i.e., a TFA flow was triggered), the OnBeforeAccountsLogin extension will not be fired.

Unique Parameters Sent

These are the parameters unique to this extension type that you can expect to receive from Gigya, followed by the full structure of the post request. These parameters are sent in addition to the common payload described above.

NameTypeDescription
dataJSON

The data object includes:

PropertyTypeDescription
accountInfoJSONThe information returned from accounts.getAccountInfo when the include parameter is set to include "data,profile,preferences,subscriptions", and extraProfileFields="address,locale,timezone".
contextJSON

This includes:

  • clientIp - The ip address of the client that made the request.
paramsJSON

This includes:

  • loginId- The identifier the user uses to login to his account. Will usually be the username or an email address.
  • password - The user's password.
  • lang - The code of the language in which to display content to this user. You can find the supported language codes here.

 

Payload Sample

Sample onBeforeAccountsLogin Payload
{
  "apiKey": "3_ve...yu",
  "callID": "806a...d0df",
  "extensionPoint": "OnBeforeAccountsLogin",
  "data": {
    "params": {
      "loginId": "test@gigya.com",
      "password": "the password passed by the user",
      "lang": "en"
    },
    "accountInfo": {
      "registeredTimestamp": 1530197465,
      "UID": "21527d...3f6",
      "created": "2018-06-28T14:50:55.859Z",
      "createdTimestamp": 1530197455,
      "data": {
        "terms": true
      },
      "subscriptions": {},
      "preferences": {},
      "isActive": true,
      "isRegistered": true,
      "isVerified": false,
      "lastLogin": "2018-06-28T14:52:23.594Z",
      "lastLoginTimestamp": 1530197543,
      "lastUpdated": "2018-06-28T14:51:05.291Z",
      "lastUpdatedTimestamp": 1530197465291,
      "loginProvider": "site",
      "oldestDataUpdated": "2018-06-28T14:50:55.859Z",
      "oldestDataUpdatedTimestamp": 1530197455859,
      "profile": {
        "firstName": "Name",
        "email": "test@gigya.com"
      },
      "registered": "2018-06-28T14:51:05.291Z",
      "socialProviders": "site"
    },
    "context": {
      "clientIP": "1.0.0.0"
    }
  }
}

Extension Response

Gigya expects to receive a response in the following structures from the extension URL.
Response indicating that Gigya should proceed as usual with the login process:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "status": "OK",
}

 

Response indicating that the login should be failed:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
   "status": "FAIL",
   "data" : {
     "userFacingErrorMessage": "string of up to 2000 characters"
   }
}

For example: 

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "status": "FAIL",
  "data": {
    "userFacingErrorMessage": "Cannot login from outside USA"
  }
}

 

OnBeforeSocialLogin

This extension point is triggered during socialize.login, right after Gigya runs the validation checks that are required for logging the user in. It is triggered in a standard login process, i.e. not in a re-authentication or link accounts scenario.

Unique Parameters Sent

These are the parameters unique to this extension type that you can expect to receive from Gigya, followed by the full structure of the post request. These parameters are sent in addition to the common payload described above.

NameTypeDescription
dataJSON

The data object includes:

PropertyTypeDescription
isNewUser BooleanIf the user is new or already exists.
accountInfo JSONOnly returned if isNewUser is FALSE. Contains all the account data of the user returned from accounts.getAccountInfo when the include parameter is set to include "data,profile,preferences,subscriptions", and extraProfileFields="address,locale,timezone".
providerIdentityJSONThe identity object containing the user's data received from the social or federated network.
context JSON

The context object includes:

  • clientIp - The ip address of the client that made the request.
params JSON

The params object includes:

  • provider - The provider that initiated the social login. This may be one of the following:
    • saml (SP)
    • oidc (OpenID Connect RP)
    • social login (All other social networks)
  • lang - The language param that was passed to the socialize.login method, default is 'en'.

 

Payload Sample

Sample onBeforeAccountsLogin Payload
{
	"apiKey":"3_ve...yu",
	"callID":"806a...d0df",
	"extensionPoint": "OnBeforeSocialLogin",
	"data": {
		"isNewUser":false,
		// If (isNewUser === true) there is NO accountInfo object returned
		"accountInfo": {
			"registeredTimestamp":73827827334,
			"UID":"",
			...,
			"profile": {},
			"data": {},
			"identities": {},
			"preferences": {},
			"subscriptions": {}
		},
		"context": {
			"clientIp":""
		},
		"params": {
			"provider":"saml",
			"lang": "en"
		},
		"providerIdentity": {
			"providerUid":"",
			"firstName":"",
			"lastName":"",
			...
			"samlData": {},
			"oidcData": {}
		}
	}
}

Extension Response

Gigya expects to receive a response in the following structures from the extension URL.
Response indicating that Gigya should proceed as usual with the login process:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "status": "OK",
}

 

Response indicating that the login should be failed:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
   "status": "FAIL",
   "data" : {
     "userFacingErrorMessage": "string of up to 2000 characters"
   }
}

For example: 

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "status": "FAIL",
  "data": {
    "userFacingErrorMessage": "Cannot login from outside USA"
  }
}

 

OnBeforeSetAccountInfo

This extension point is triggered during  accounts.setAccountInfo, immediately before account data is written to the database. This extension may be used for validation or data enrichment. Data enrichment can be achieved by returning an 'ENRICH' status from the extension service, and the data to set to the profile. 


Unique Parameters Sent
 

These are the parameters unique to this extension type that you can expect to receive from Gigya, followed by the full structure of the post request. These parameters are sent in addition to the common payload described above. 

NameTypeDescription
dataJSON

The data object includes:

PropertyTypeDescription
addLoginEmailsstringA comma-separated list of emails that is added to the user's login identifiers list, and can be used for login purposes.
dataJSONCustom data associated with this user.
isActiveBooleanIndicates whether this account is enabled.
isVerifiedBooleanIndicates whether the account email(s) have been verified.
newPasswordstringUsed together with password, the new password to replace the old one.
passwordstringUsed together with newPassword, the old password being changed.
profileJSONThe user's Profile Object.
subscriptionJSONThe Subscriptions Object, containing subscription information for this user.
regSourcestringA string representing the source of the registration.
removeLoginEmailsBooleanA comma-separated list of emails to be removed from the user's list of login identifiers.
requirePasswordChangeBooleanIndicates whether the user will be required to change password on the next login.
secretAnswerstringA secret answer to the secret question that may be used for verification.
secretQuestionstringA secret question that may be used for verification. 
usernamestringThe unique name the user chose for themselves.
rbaJSON array

The RBA policy associated with this user. Available properties include: 

  • riskPolicy (string) - The rule set that applies to the user.
  • riskPolicyLocked (Boolean) - Whether the user can change their own riskPolicy. If true, only an admin can change the user's riskPolicy.

preferences JSONThe Preferences Object, containing consent information for this user.
langstringThe code of the language in which to display content to this user. You can find the supported language codes here.
accountInfoJSONThe information returned from accounts.getAccountInfo when the include parameter is set to include "data,profile,preferences,subscriptions", and extraProfileFields="address,locale,timezone".
contextJSON

The context object includes:

  • clientIp - The ip address of the client that made the request.
paramsJSON

The params object includes:

  • provider - The provider that initiated the social login.
  • datacenter - The datacenter that the request was made on.


Payload Sample

 

Sample onBeforeSetAccountInfo Payload
{
  "apiKey": "3_v...yu",
  "callID": "875796577b0444b79f6ec6592bf40d30",
  "extensionPoint": "OnBeforeSetAccountInfo",
  "data": {
    "params": {
      "profile": {
        "firstName": "test"
      },
      "secretAnswer": "success",
    },
    "accountInfo": {
      "registeredTimestamp": 1530606852,
      "UID": "b1c...43",
      "created": "2018-07-03T08:34:10.815Z",
      "createdTimestamp": 1530606850,
      "data": {},
      "subscriptions": {},
      "preferences": {},
      "isActive": true,
      "isRegistered": true,
      "isVerified": false,
      "lastLogin": "2018-07-03T09:15:31.487Z",
      "lastLoginTimestamp": 1530609331,
      "lastUpdated": "2018-07-03T09:15:33.568Z",
      "lastUpdatedTimestamp": 1530609333568,
      "loginProvider": "site",
      "oldestDataUpdated": "2018-07-03T08:34:10.815Z",
      "oldestDataUpdatedTimestamp": 1530606850815,
      "profile": {
        "email": "test1@test.com""
      },
      "registered": "2018-07-03T08:34:12.041Z",
      "socialProviders": "site"
    }
  }
}

Extension Response

Gigya expects to receive a response in the following structures from the extension URL.
In an enrichment scenario, the response may include the following: 
  • data: JSON object of custom data set to the 'data' namespace
  • profile: the Profile Object
  • removeLoginEmails: a list of emails to remove from the list of loginIDs for this user.
Response indicating that Gigya should proceed as usual with updating the user's profile:

 

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "status": "OK",
}

 

Response indicating that the user's profile update should be stopped:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "status": "FAIL",
  "data": {
     "validationErrors" : [ // Array of up to 50 items, in the following structure:
       {
        "fieldName": string up to 200 characters - the name of the field that had an issue
        "message": string up to 2000 characters  - the custom error message the user will see in regard with this field
      }
    }
  ]
}

 

For example: 

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "status": "FAIL",
  "data": {
    "validationErrors": [
      {
        "fieldName": "profile.email",
        "message": "email should belong to domain 'gigya.com'"
      },
      {
        "fieldName": "profile.firstName",
        "message": "We consider this word offensive, please use something else"
      }
    ]
  }
}

 

Data enrichment response sample: 

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
 
{
  "status": "ENRICH",
  "data": {
    "profile": {firstName: "firstName", zip: 12345},
    "data": {dataField1: "dataField1"},
    "removeLoginEmails": "emailToRemove@gmail.com"
  }
}

 

OnBeforeSendSMS

Use this extension to apply your own logic to any SMS that is triggered from SAP Customer Data Cloud, both in Risk Based Authentication and Phone Number Login scenarios, including:

  • Send an SMS from a provider that is not Twilio or Livelink
  • Apply limitations on the number of SMS sent out at certain times
  • Perform analytics on your SMS service
  • Apply custom validations to the user's phone number
  • Use advanced options with Twilio or Livelink that are not supported by Gigya configurations

When this extension is enabled, SAP Customer Data Cloud will not necessarily send the SMS code directly to the user, but instead send it with the extension payload to your endpoint, to be handled on your end: you can choose whether to allow Gigya to send the SMS, send an SMS from your own provider, or fail the flow. This extension point is triggered by the accounts.otp.sendCode and accounts.tfa.phone.sendVerificationCode, right after Gigya runs the validation checks that apply to sending a verification code to a user. 

The following diagram describes the OnBeforeSendSMS flow: 

 

Unique Parameters Sent

These are the parameters unique to this extension type that you can expect to receive from Gigya, followed by the full structure of the post request. These parameters are sent in addition to the common payload described above. 
NameTypeDescription
dataJSON

The data object includes:

PropertyTypeDescription
phoneNumberstringThe user's phone number.
messagestringA message containing the verification code sent to the user.


Payload Sample

Sample OnBeforeSendSMS Payload
 {
	"apiKey":"3_ve...yu",
	"callID":"806a...d0df",
	"extensionPoint": "OnBeforeSendSms",
	“data”: {
		“phoneNumber”: “+9720511888183”,
		“message”: “Hello, this is your code: 123”,
	}
}

Extension Response

Using the status field, the SMS extension can tell Gigya the following: 

  • OK: The SMS was handled by the extension point, don't send an SMS to the user
  • CONTINUE: The SMS should be sent from Gigya to the user
  • FAIL: Don't send an SMS, instead show an error message

Response indicating that the SMS was handled by the endpoint and Gigya should not send it to the user: 

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
 "status": "OK",
}

 

Response indicating that Gigya should proceed as usual with the SMS delivery process:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
 "status": "CONTINUE",
}

 

Response indicating that the SMS code send should be failed:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
 "status": "FAIL",
 "data": {
 "userFacingErrorMessage": "Invalid phone number"
 }
}

 

Full Code Sample

The following code sample demonstrates 3 simple validations performed using the three extension endpoints: 

  • OnBeforeAccountsRegister: Prevent users from registering with any domain but the "xyz" domain. Also, display a different message for a Hebrew-speaking user. 
  • OnBeforeAccountsLogin: Block the user from logging in if their first name is "Block" and the last name is "Me". Also, display a different message for a Hebrew-speaking user. 
  • OnBeforeSetAccountInfo: 
    • Validation: Prevent the user from changing their name to one that contains a negative word, in this case, "fail". Also, display a different message for a Hebrew-speaking user. 
    • Enrichment: In the profile.firstName field, transform a lower case first letter to upper case.

 

Following is a full JavaScript code sample for a node.JS application:

Extension Full Code Sample
 
function handleExtensionsRequest(request, response) {
    var ret = {status: "OK"};
     
    if (request.body.extensionPoint === "OnBeforeAccountsRegister") {
        if (!request.body.data.params.email.endsWith('@xyz.com')){
            ret.status = "FAIL";
            var customMessage = "Email should belong to domain 'xyz.com'";
            if (request.body.data.params.lang === "he")
                customMessage = "אימייל צריך להיות בדומיין איקס ווי זד";
            ret.data = {
                validationErrors: [
                    { fieldName: "profile.email", message: customMessage },
                ]
            }
        }
    }
    else if (request.body.extensionPoint === "OnBeforeAccountsLogin") {
        if (request.body.data.accountInfo !== undefined &&
            request.body.data.accountInfo.profile !== undefined &&
            request.body.data.accountInfo.profile.firstName === "block" &&
            request.body.data.accountInfo.profile.lastName === "me") {
            ret.status = "FAIL";
            var customMessage = "Your account is temporarly blocked";
            if (request.body.data.params.lang === "he")
                customMessage = "חשבונך חסום באופן זמני";
            ret.data = {
                userFacingErrorMessage: customMessage
            };
        }
    }
    else if (request.body.extensionPoint === "OnBeforeSetAccountInfo"){
        if (request.body.data.params.profile !== undefined &&
            request.body.data.params.profile.firstName !== undefined &&
            request.body.data.params.profile.firstName.includes("fail"))
        {
            ret.status = "FAIL";
            var customMessage = "Invalid name - contains a word with a negetive meaning";
            var firstLetter = request.body.data.params.profile.firstName.charAt(0);
            if (request.body.data.params.lang === "he")
                customMessage = "שם לא חוקי - מכיל מילה עם משמעות שלילית";
            ret.data = {
                validationErrors: [
                    { fieldName: "profile.firstName", message: customMessage }
                ]
            };
            else if(firstLetter == firstLetter.toLowerCase()
            {
                ret.status = "ENRICH"
                ret.data = {
                    profile: { firstName: firstLetter.toUpperCase()+ firstName.slice(1) }
                };
            }
        }
    }
     
    response.setHeader('Content-Type', 'application/json');
    response.send(JSON.stringify(ret));
}

 

This is how it would appear to end users: 

A user trying to register with domain "x": 

 

Will receive a custom error: 

 

And when registering with that domain when the 'lang' parameter is "he"(Hebrew): 

 

Now the user tries to change their first name:

 

A blocked user attempts to register: 

 

Viewing Extension Logs

A log is written every time an attempt is made to call an extension. 

 

To view the extension logs: 

  1. Open the Extensions page of Gigya's Console. 
  2. Open the Logs tab. 
  3. By default, log records from the last 7 days are displayed, sorted by the time they were recorded in descending order, up to a limit of 1,000 entries. 


Log Filters

You can filter the results to locate a specific log record. 

  • Time Range: the time at which the call was recorded. 
  • Extension Point: the type of the extension that was called.
  • Call ID: the unique identifier of the call. 

Call Details

The tooltips in the first table column indicate which response was received from the extension: 

 ("v" icon): The extension sent a valid response, and allowed Gigya's flow to proceed ("green light"). 

 ("x" icon): The extension sent a malformed response, or the response took too long. The flow was allowed to continue or stopped, depending on the configuration of the fallout policy. 

 ("!" icon): The extension sent a valid response that indicated to Gigya that the flow should be stopped. 

The following information is available for each call recorded in the logs: 

  • Timestamp: the date and time at which the call was made. 
  • Duration: the duration of the call. 
  • Data Center: the data center from which the call was made.
  • Extension Point: the extension type (e.g., onBeforeAccountsRegister). 
  • Message: the message returned from the extension service in regards to this extension call. 

IP Whitelisting

You should ensure that your systems that interact with Gigya Extensions can access to the relevant IP addresses. If your system administrators explicitly whitelist IPs, see Whitelisting Gigya IP Addresses. Extensions use the IPs listed under "NAT IPs". 

 

Additional Information

Associated Rest APIs include the following:

 

Unable to render {include} The included page could not be found.

 

 

 

 


 
  • No labels