Tutorial: Real-time validation of login via Email or unique codes using HTTPS calls or integration Follow
The login system via email or code from Easypromos is used to allow or deny access to users in promotions managed with Easypromos.
In the case of email validation, the system previously validated the format of the email and optionally sent a confirmation email to the user's email address, so that they could certify that it was indeed them requesting access to the promotion.
In the case of code validation, we already had several options to validate the code entered by the user (regular expression, set of codes, Luhn algorithm).
In this update, we have added new validation options via email and code that will be very useful to the administrators of our campaigns.
In the case of email validation, these new options are accessible from the "Email Restrictions" selector, as shown in the following image:
In the case of validation by "Customer Number," you can find a new option in the code validation selector, "Via external API (Webservice)," as shown in this image:
The options in the two types of validations are:
Next, we detail each of the options.
1. Login with email validation
1.1. Restriction by domain
This restriction allows administrators to restrict the domains of the email addresses of users who wish to participate in a promotion. Only emails belonging to the domain(s) listed in the specified domain list will have access. This restriction is especially interesting when a company wants to limit entry to a campaign to users with a corporate email.
Below, we show an example of the configuration for the restriction by email domains. In this case, we would only allow emails with the format xxx@my-domain.com or yyy@mycompany.com
1.2. Restriction by a closed list of emails
This restriction allows the administrator to filter the registration in the promotion only to users with emails that appear on the list. A "codeset" must first be created within the promotion, with the detailed list of all the email addresses that will be allowed to enter.
This case is useful when you have a list of emails from participants in an event and want only these people to be able to enter the promotion and receive a prize, for example.
The validation of the email addresses is performed without considering case sensitivity; for example, if you have added the email: Firstname.Lastname@gmail.com in the list, the emails firstname.Lastname@gmail.com, Firstname.Lastname@gmail.com, and also firstNAME.laSTNAME@gmail.com would all be valid, along with all possible combinations of uppercase and lowercase letters.
1.3. Integration with a Mailchimp list
You can also restrict the registration in the promotion by detecting if the email is subscribed to a Mailchimp mailing list. To do this, you will need to enter the Mailchimp API Key and then select the list you want to use to allow user access.
This functionality allows you, for example, to let users of your newsletter access the promotion to win prizes or participate in exclusive games. The advantage of this integration is that access is updated in real-time with the subscribers of the Mailchimp list, thus avoiding data synchronization issues.
1.4. Integration via client HTTPS REST generic API
This option allows real-time validation of the email entered by the user against a web service programmed by the client.
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
The configuration of Headers is especially important as it allows for the protection of the client URL with private tokens and prevents the API from being queried with potential brute-force attacks. API requests are made from server to server, so these tokens will never be visible from the user's browser.
Webservice URL
The service URL must point to the endpoint programmed by the client. This endpoint must accept a parameter {EMAIL} in the URL itself or as a GET parameter.
Examples of valid URLs to check the email:
- https://mypromo.com/validate/{EMAIL}, for example, https://mypromo.com/validate/aaa@gmail.com
- https://mypromo.com/{EMAIL}/validate, for example, https://mypromo.com/aaa@gmail.com
- https://mypromo.com/validate?email={EMAIL}, for example, https://mypromo.com/validate?email=aaa@bb.com
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, 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."
2. In code validation
2.1. Integration via client HTTPS REST generic API
This option allows real-time validation of the code entered by the user against a web service programmed by the client.
Currently, calls to URLs via HTTPS using the GET method are supported, expecting a response of type JSON.
The URL must respond with a code 200 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
The configuration of Headers is especially important, as it allows for the protection of the client URL with private tokens and prevents the API from being queried with potential brute-force attacks. API requests are made from server to server, so these tokens will never be visible from the user's browser.
Webservice URL
The service URL must point to the endpoint programmed by the client. This endpoint must accept a parameter {CUSTOMER_NUMBER} in the URL itself or as a GET parameter.
Examples of valid URLs to check the email:
- https://mypromo.com/validate/{CUSTOMER_NUMBER}, for example, https://mypromo.com/validate/aaa
- https://mypromo.com/{CUSTOMER_NUMBER}/validate, for example, https://mypromo.com/aaaa/validate
- https://mypromo.com/validate?code={CUSTOMER_NUMBER}, for example, https://mypromo.com/validate?code=aaaa
Testing
You can use the [Run a test] function to try different codes and see the response. For each code 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 code, and another that returns a code 404, rejecting any code.
These URLs are:
- https://wl.easypromosapp.com/v24/ok/{CUSTOMER_NUMBER} - For the case of all OK
- https://wl.easypromosapp.com/v24/ko/{CUSTOMER_NUMBER} - For the case of all ERROR
If, for example, we configure the always-error URL in the Editor of a promotion as we see in this image:
The user or you when testing the participation flow in the promotion will never be able to register in the promotion as an error will always be returned in the login step:
Of course, these URLs are only for testing purposes. The client must implement a public URL where a code can be sent to be validated. To prevent malicious use of these URLs, security tokens can be sent using the header fields.
Note: these login restriction features via email and code are only available in the White Label or superior versions of Easypromos.
Comments
0 comments
Please sign in to leave a comment.