Class PhoneVerification

java.lang.Object
com.codename1.ui.Component
com.codename1.ui.Container
com.codename1.components.PhoneVerification
All Implemented Interfaces:
Animation, Editable, StyleListener, Iterable<Component>
public class PhoneVerification extends Container

The two stages of verifying that a user holds a phone number: enter the number, then enter the code that arrives by SMS.

The application supplies both server calls. This component owns everything around them: the number entry, the code entry, the wait before a resend is offered, the way back to a mistyped number, and the errors either call reports.

Example
PhoneVerification verify = new PhoneVerification();
verify.setCodeSender((number, response) -> myServer.sendSms(number, response));
verify.setCodeVerifier((number, code, response) -> myServer.check(number, code, response));
verify.addVerifiedListener(e -> showMainScreen());
form.add(verify);

A sender is handed the number and a Response, and calls exactly one of Response#succeeded() or Response#failed(String) when its server answers -- from any thread. Until then the button it came from stays disabled, so a second tap cannot send a second message.

The code is offered by the platform

The code field is an OtpField, so it carries the one-time-code hint and the platform offers the arriving code on the keyboard or through autofill. Nothing here reads messages, and no messaging permission is involved.

Styling

The component uses the UIID "PhoneVerification", its explanatory lines "PhoneVerificationText", its error line "PhoneVerificationError" and its buttons "PhoneVerificationButton" -- except the resend and change-number buttons, which use "PhoneVerificationLink".

  • Constructor Details

    • PhoneVerification

      public PhoneVerification()
      Builds the flow with a six digit code.

    • PhoneVerification

      public PhoneVerification(int codeLength)

      Builds the flow with a code of the given length.

      Parameters
      • codeLength: the number of digits in the code

  • Method Details

    • showNumberStage

      public void showNumberStage()
      Returns to the first stage, with the number as it was left, and clears any code that was typed.

    • showCodeStage

      public void showCodeStage(String e164Number)

      Moves to the code stage for a number, as though the code had just been sent. Useful when the application sent the message itself rather than through #setCodeSender(CodeSender).

      Parameters
      • e164Number: the number the code went to

    • isCodeStage

      public boolean isCodeStage()
      True when the code stage is showing.

    • requestCode

      public void requestCode(String e164Number)

      Sends a code to a number, moving to the code stage when the server accepts it. Called by the send and resend buttons; an application driving the flow from its own button calls it directly.

      Parameters
      • e164Number: the number to send to

    • isPlausibleE164

      public static boolean isPlausibleE164(String e164Number)

      The shape a number must have before a request is worth making: a "+", then between five and fifteen digits, which is what E.164 allows. It is not a check that the number exists -- that is the sending service's answer, and its refusal is shown to the user like any other failure.

      Parameters
      • e164Number: the number to check
      Returns

      true when the number is worth sending to

    • submitCode

      public void submitCode()
      Verifies the code currently entered. Called when the last box is filled and by the verify button.

    • deinitialize

      protected void deinitialize()
      Description copied from class: Component
      Invoked to indicate that the component initialization is being reversed since the component was detached from the container hierarchy. This allows the component to deregister animators and cleanup after itself. This method is the opposite of the initComponent() method.
      Overrides:
      deinitialize in class Component

    • initComponent

      protected void initComponent()
      Description copied from class: Component
      Allows subclasses to bind functionality that relies on fully initialized and "ready for action" component state
      Overrides:
      initComponent in class Component

    • setCodeSender

      public void setCodeSender(PhoneVerification.CodeSender codeSender)

      Sets the server call that sends a code to a number.

      Parameters
      • codeSender: the sender

    • setCodeVerifier

      public void setCodeVerifier(PhoneVerification.CodeVerifier codeVerifier)

      Sets the server call that checks a code.

      Parameters
      • codeVerifier: the verifier

    • getResendDelay

      public int getResendDelay()
      The seconds the user waits before a resend is offered; 60 by default.

    • setResendDelay

      public void setResendDelay(int seconds)

      Sets the seconds before a resend is offered. Zero offers it at once.

      Parameters
      • seconds: the delay

    • getPhoneNumber

      public String getPhoneNumber()
      The number the code was sent to, in E.164 form, or null before a code has been requested.

    • getPhoneNumberField

      public PhoneNumberField getPhoneNumberField()
      The number entry field, exposed for theming and for narrowing the country list.

    • getOtpField

      public OtpField getOtpField()
      The code entry field, exposed for theming.

    • getSendButton

      public Button getSendButton()
      The button that sends the first code, exposed for theming and for relabelling.

    • getVerifyButton

      public Button getVerifyButton()
      The button that submits a typed code, exposed for theming. The code is also submitted as soon as the last box is filled.

    • getResendButton

      public Button getResendButton()
      The button that asks for another code, exposed for theming.

    • getChangeNumberButton

      public Button getChangeNumberButton()
      The button that returns to the number stage, exposed for theming.

    • addVerifiedListener

      public void addVerifiedListener(ActionListener l)

      Adds a listener fired when a code is accepted.

      Parameters
      • l: the listener

    • removeVerifiedListener

      public void removeVerifiedListener(ActionListener l)

      Removes a previously-registered listener.

      Parameters
      • l: the listener

    • addFailedListener

      public void addFailedListener(ActionListener l)

      Adds a listener fired when either server call reports a failure. The failure is already shown to the user; this is for an application that wants to count attempts or log them.

      Parameters
      • l: the listener

    • removeFailedListener

      public void removeFailedListener(ActionListener l)

      Removes a previously-registered listener.

      Parameters
      • l: the listener