com.veriplace.client
Class InvitationAPI

java.lang.Object
  com.veriplace.client.AsyncCapableAPI<InvitationStatus>
      com.veriplace.client.InvitationAPI

public class InvitationAPI
extends AsyncCapableAPI<InvitationStatus>

Interface for initiating an SMS invitation from Veriplace to an end user, allowing the user to opt into this application. To access an instance of this class, use Client.getInvitationAPI().

Note that this feature is currently enabled on a per-application basis and is disabled by default. Contact Veriplace Developer Support to request that it be enabled for your application.

Since:

2.3

See Also:

Veriplace Developer Guide: Using the Invitation API

Method Summary

InvitationStatus	getCallbackResult(HttpServletRequest request, HttpServletResponse response) Process the parameters of an HTTP callback that was posted from Veriplace as the result of an invitation.
InvitationStatus	getInvitationStatus(HttpServletRequest request) Deprecated. Use getCallbackResult(HttpServletRequest, HttpServletResponse).
InvitationStatus	getResult(InvitationStatus request) Check the status of an invitation that was previously submitted with inviteGetLocation(String, String, boolean).
InvitationStatus	inviteGetLocation(java.lang.String mobileNumber, boolean sendUserConfirmation, CallbackOptions callbackOptions) Invite a user to grant Get Location permission to this application, by sending a message to the user's mobile device.
InvitationStatus	inviteGetLocation(java.lang.String mobileNumber, java.lang.String callbackUri, boolean sendUserConfirmation) Invite a user to grant Get Location permission to this application, by sending a message to the user's mobile device.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

inviteGetLocation

public InvitationStatus inviteGetLocation(java.lang.String mobileNumber,
                                          java.lang.String callbackUri,
                                          boolean sendUserConfirmation)
                                   throws InvitationNotPermittedException,
                                          UnknownTokenException,
                                          BadParameterException,
                                          UnexpectedException

Invite a user to grant Get Location permission to this application, by sending a message to the user's mobile device.

If allowable - and if the application doesn't already have permission - the user will receive a text message from Veriplace with options to accept or decline the invitation, and to register with Veriplace if the user wasn't already registered.

You may poll for the result with getResult(InvitationStatus), or specify a callback URI to which Veriplace should post the result. This version generates only a summary message in the callback; to get the full result by callback, use inviteGetLocation(String, boolean, CallbackOptions).

Note that if an application is in development and has not yet been published, it can only invite developer-mode users (i.e. the numbers on its Test Phones list).

To use this method, you must have configured the client with an application-specific access token.

Parameters:

mobileNumber - the mobile number of the user to be invited; see UserDiscoveryParameters for acceptable mobile number formats

callbackUri - the URI at which this application expects to receive a callback request, or null if the application will poll for the result

sendUserConfirmation - true if Veriplace should send the user a final SMS after the user accepts or declines the invitation, to confirm the result; false to skip that step (pass false only if your application has some other mechanism for notifying the user on completion)

Returns:

an InvitationStatus object which contains either a unique identifier for the request, or else a user identifier if the request was unnecessary; in the latter case, InvitationStatus.isCompleted() will be true and you will not receive a callback

Throws:

InvitationNotPermittedException - if the invitation is not possible because of limitations on the application's privileges, or the user being on an incompatible network

BadParameterException - if the mobile number or callback URI was not in a valid format

UnknownTokenException - if the application-specific access token is invalid

UnexpectedException - if there was an unexpected I/O error or OAuth error

inviteGetLocation

public InvitationStatus inviteGetLocation(java.lang.String mobileNumber,
                                          boolean sendUserConfirmation,
                                          CallbackOptions callbackOptions)
                                   throws InvitationNotPermittedException,
                                          UnknownTokenException,
                                          BadParameterException,
                                          UnexpectedException

Invite a user to grant Get Location permission to this application, by sending a message to the user's mobile device.

If allowable - and if the application doesn't already have permission - the user will receive a text message from Veriplace with options to accept or decline the invitation, and to register with Veriplace if the user wasn't already registered.

This version of the method takes a CallbackOptions parameter, which, if not null, can specify both a callback URI for receiving the result of the request and additional options for the format of the result message. You can process the callback message with getCallbackResult(HttpServletRequest, HttpServletResponse). If you don't specify a callback, use getResult(InvitationStatus) to poll for the result.

Note that if an application is in development and has not yet been published, it can only invite developer-mode users (i.e. the numbers on its Test Phones list).

To use this method, you must have configured the client with an application-specific access token.

Parameters:

mobileNumber - the mobile number of the user to be invited; see UserDiscoveryParameters for acceptable mobile number formats

sendUserConfirmation - true if Veriplace should send the user a final SMS after the user accepts or declines the invitation, to confirm the result; false to skip that step (pass false only if your application has some other mechanism for notifying the user on completion)

callbackOptions - an optional CallbackOptions object specifying how Veriplace should post the result back to you when ready; null if you will poll for the result

Returns:

an InvitationStatus object which contains either a unique identifier for the request, or else a user identifier if the request was unnecessary; in the latter case, InvitationStatus.isCompleted() will be true and you will not receive a callback

Throws:

InvitationNotPermittedException - if the invitation is not possible because of limitations on the application's privileges, or the user being on an incompatible network

BadParameterException - if the mobile number or callback URI was not in a valid format

UnknownTokenException - if the application-specific access token is invalid

UnexpectedException - if there was an unexpected I/O error or OAuth error

Since:

2.8

getResult

public InvitationStatus getResult(InvitationStatus request)
                           throws RequestNotFoundException,
                                  UnexpectedException

Check the status of an invitation that was previously submitted with inviteGetLocation(String, String, boolean). Use this method if you did not specify a callback URI in the original request.

If the user has not yet responded to the invitation, this will return the same request status object. If the user has either accepted or declined the invitation, it will return an updated request status object whose AsyncRequestStatus.isReady() method will return true, and whose other properties will describe the result.

Overrides:

getResult in class AsyncCapableAPI<InvitationStatus>

Parameters:

request - the original invitation status object

Returns:

an updated invitation status object of the same type

Throws:

RequestNotFoundException - if the request is no longer valid, i.e. it has expired or the result was already delivered via a callback notification

UnexpectedException - if there was an unexpected OAuth error or I/O error, or if the request is no longer valid

getCallbackResult

public InvitationStatus getCallbackResult(HttpServletRequest request,
                                          HttpServletResponse response)
                                   throws UnexpectedException

Process the parameters of an HTTP callback that was posted from Veriplace as the result of an invitation.

The resulting InvitationStatus object will contain either a Veriplace user identifier (InvitationStatus.getUser(), if the user accepted the invitation, or an error (InvitationStatus.getException()).

If you used the extended callback mode (see CallbackOptions), it will also contain the mobile number from the original invitation and, if successful, the access token for locating the user. If you used the summary callback mode, it will not contain either of those properties; you will need to keep track of the mobile number yourself (associating it with the invitation's request ID), and you can query the access token with GetLocationAPI.getLocationAccessToken(User).

To confirm receipt of the callback, this method also sends an immediate HTTP 200 ("OK") response to Veriplace, completing the HTTP response. Do not try to do anything else with the response object after this; if your application returned anything else, or did not respond, Veriplace would repeat the callback.

Overrides:

getCallbackResult in class AsyncCapableAPI<InvitationStatus>

Parameters:

request - the current HTTP request

response - the current HTTP response (see above)

Returns:

an InvitationStatus object

Throws:

UnexpectedException - if the request did not contain valid parameters

getInvitationStatus

@Deprecated
public InvitationStatus getInvitationStatus(HttpServletRequest request)
                                     throws UnexpectedException

Deprecated. Use getCallbackResult(HttpServletRequest, HttpServletResponse).

Throws:

UnexpectedException