Tutorial: Real-time Login Validation via Email or Customer Code Using Web service Follow
Easypromos allows real-time validation of the email addresses entered by users during the promotion registration process against an external user system. This enables the creation of promotional campaigns where only users existing in a database maintained by a client, such as newsletter subscribers, a CRM of contacts, or a loyalty program, can participate.
This real-time validation feature works for both email validations and unique user codes, such as employee numbers, customer numbers, loyalty numbers, etc.
Examples of use:
- Create a sweepstake for newsletter subscribers: When the user registers for the sweepstake, the system will validate in real-time whether the user is part of the newsletter. If not, the user will see a message indicating they need to subscribe to the newsletter with a direct link.
- Create a prize wheel game where users must enter their loyalty customer number to participate: The system will validate in real-time that the number entered by the user is part of the loyalty customer database.
NOTE: This functionality applies when the identification and registration process happens within Easypromos, meaning users must complete the promotion registration form. If you are looking for a Single Sign-On (SSO) solution, where the user is authenticated directly in your system, you should use the Autologin API or the integration with Open ID Connect.
Requirements and Initial Configurations
These are the requirements that the person managing the promotion, who does not necessarily have to be the developer, must meet and verify.
The following requirements are needed to establish the connection:
- A White Label or Corporate plan is required. This is not included in Premium or Basic plans.
- The promotion version must be White Label. It does not apply to Premium promotions.
- The identification/Login screen must be enabled. It does not apply when the one-step login and registration system is activated.
- This feature only applies to the following login methods:
- Email (if you are validating email addresses)
- Customer code (if you are validating customer numbers)
Once these requirements are met, for email validation, the identification and registration screen must be configured as follows:
- Access the Promotion Editor
- Go to Pages > Login and Registration > Login Tab
- Ensure that the option "One-step identification and registration process" is disabled.
- Enable Login with Email and, in its options, enable Email Restrictions "Via external API (Web service)". If instead of validating emails, you want to validate customer codes, you should enable the "Login with customer code" option.
- The Method, Content-type, Headers, and Web service URL must be provided by the integration developer. This is explained in the next section of the tutorial.
- Error message: Enter the text a user will see in case of a validation error. Take advantage of this by including a link to your system for registration. Example: "The email is not valid. If you are not yet a subscriber, sign up here."
For Developers: Integration via client HTTPS REST generic API
This section of the tutorial is specifically aimed at developers or technical integrators responsible for setting up the connection with the external web service. You will need to handle the configuration of the API, including headers, methods, and the web service URL, to enable real-time validation.
Currently, calls to URLs via HTTPS using the GET method are supported, expecting a JSON response type .
The URL must respond with a 200 code if the email has access to the promotion. If any other code is received, it will be interpreted that the user does not have access to the promotion.
Since this is a real-time check, each time the user enters the code, a call to the web service is made. This call has a 2-second timeout. Therefore, the implementation of the web service must be able to return the 200 code in less than two seconds to avoid negatively impacting the user experience; otherwise, the validation will fail.
Headers
Configure the headers of the request with the authentication requirements of your web service.
Header configuration is especially important as it allows the client's URL to be protected with private tokens and prevents the API from being accessed through potential brute force attacks. Requests to the API are made server-to-server, so these tokens will never be visible from the user's browser.
Web service URL
The service URL must point to the endpoint programmed by the client. This endpoint requires that the variable {EMAIL} be added to the URL itself or as a GET parameter. This variable will be replaced by the email entered by the user.
Examples of valid URLs to check the email:
https://mypromo.com/validate/{EMAIL} | https://mypromo.com/validate/aaa@gmail.com |
https://mypromo.com/validate?email={EMAIL} | https://mypromo.com/validate?email=aaa@gmail.com |
https://mypromo.com/{EMAIL}/validate | https://mypromo.com/aaa@gmail.com/validate |
If instead of validating emails, you are validating customer codes, you should use the {CUSTOMER_NUMBER} parameter.
https://mypromo.com/validate/{CUSTOMER_NUMBER} | https://mypromo.com/validate/66778A3R |
https://mypromo.com/validate?code={CUSTOMER_NUMBER} | https://mypromo.com/validate?email=66778A3R |
https://mypromo.com/{CUSTOMER_NUMBER}/validate | https://mypromo.com/66778A3R/validate |
Testing
You can use the [Run a test] function to try different emails and see the response. For each email entered, the response from the web service is shown in the test pop-up screen, for example:
To test this function before programming the final URL, we have created two test URLs: one that always responds with a code 200, accepting the email, and another that returns a code 404, rejecting any email.
These URLs are:
- https://wl.easypromosapp.com/v24/ok/{EMAIL} - To test the OK answer
- https://wl.easypromosapp.com/v24/ko/{EMAIL} - To test the ERROR answer
If you are validating customer codes instead of emails, the URLs are:
- https://wl.easypromosapp.com/v24/ok/{CUSTOMER_NUMBER} - For the case where everything is OK
- https://wl.easypromosapp.com/v24/ko/{CUSTOMER_NUMBER} - For the case where there is an ERROR
If, for example, you configure the always-error URL in the editor of your promotion as shown in the following image:
When testing the user experience, you will never be able to register in the promotion as an error will always be returned by the system.
Of course, the two testing URLs are only for you to run trials. You must implement a public URL where an email can be sent for validation. To prevent malicious use of these URLs, security tokens can be sent using the header fields."
NOTE: If this external web service call configuration does not fit your current service, it will be necessary to program and host an intermediary connector to interconnect the two services. If you need a connector, you can contact our Easypromos sales team to request a quote for the development, hosting, and maintenance of the connector.
Comments
0 comments
Please sign in to leave a comment.