Docs For Class Veriplace

Description

Interface for initiating an invitation from Veriplace to an end user, allowing the user to opt into this application.

The application can choose to receive an HTTP callback from Veriplace when the user completes (or declines) this transaction, or can poll for the result.

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.

See Veriplace Developer Guide: Using the Invitation API for more details.

since: 1.2

Located in /Veriplace/Client.php (line 1486)

Veriplace_API
   |
   --Veriplace_AsyncCapableAPI
      |
      --Veriplace_InvitationAPI

Method Summary

Veriplace_InvitationStatus getCallbackResult ()

void getInvitationStatus ()

Veriplace_InvitationStatus getResult (Veriplace_InvitationStatus $request)

Veriplace_InvitationStatus inviteGetLocation (string $mobileNumber, Veriplace_CallbackOptions $callbackOptions, boolean $sendUserConfirmation)

Methods

getCallbackResult (line 1604)

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

The resulting Veriplace_InvitationStatus object will contain either a Veriplace user identifier (in the Veriplace_InvitationStatus::$user property), or an error (Veriplace_AsyncRequestStatus::$exception).

If you used the extended callback mode (see Veriplace_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 Veriplace_GetLocationAPI::getLocationAccessToken().

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.

return: A Veriplace_InvitationStatus object
throws: Veriplace_UnexpectedException if the request did not contain valid parameters
access: public

Veriplace_InvitationStatus getCallbackResult ()

Redefinition of:

Veriplace_AsyncCapableAPI::getCallbackResult()

getInvitationStatus (line 1573)

deprecated: Use getCallbackResult().
access: public

void getInvitationStatus ()

getResult (line 1631)

Attempt to retrieve the result of an invitation that was previously submitted with inviteGetLocation(). Use this method if you did not specify a callback URI in the original request.

If the invitation is still in progress, this will return the same status object. If the invitation has completed, either successfully or unsuccessfully, it will return an updated status object whose Veriplace_AsyncRequestStatus::$ready property will be true, and which will either contain a Veriplace_User object (Veriplace_InvitationStatus::$user) or an error (Veriplace_AsyncRequestStatus::$exception).

return: an updated status object of the same type
throws: Veriplace_UnexpectedException if there was an unexpected OAuth error or I/O error
throws: Veriplace_RequestNotFoundException if the request is no longer valid, i.e. it has expired or the result was already delivered via a callback notification
access: public

Veriplace_InvitationStatus getResult (Veriplace_InvitationStatus $request)

Veriplace_InvitationStatus $request: the original invitation status object

Redefinition of:

Veriplace_AsyncCapableAPI::getResult()

inviteGetLocation (line 1536)

Invite a user to grant Get Location permission to this application.

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.

When the user accepts or declines, Veriplace will send an HTTP POST request to the specified callback URI. Note that this is not a callback in the sense of the browser redirects used in OAuth exchanges, but a direct server-to-server HTTP request. See getCallbackResult() for how to process the callback.

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.

return: a Veriplace_InvitationStatus object which contains either a unique identifier for the request (Veriplace_AsyncRequestStatus::$id), or else a user identifier if the request was unnecessary (Veriplace_InvitationStatus::$user); in the latter case, you will not receive a callback
throws: Veriplace_InvitationNotPermittedException if the invitation is not possible because of limitations on the application's privileges, or the user being on an incompatible network
throws: Veriplace_UnexpectedException if there was an unexpected I/O error or OAuth error
throws: Veriplace_BadParameterException if the mobile number or callback URI was not in a valid format
throws: Veriplace_UnknownTokenException if the application-specific access token is invalid
access: public

Veriplace_InvitationStatus inviteGetLocation (string $mobileNumber, Veriplace_CallbackOptions $callbackOptions, boolean $sendUserConfirmation)

string $mobileNumber: The mobile number of the user to be invited; see Veriplace_UserDiscoveryParameters for acceptable mobile number formats
Veriplace_CallbackOptions $callbackOptions: An optional Veriplace_CallbackOptions object specifying how Veriplace should post the result back to you when ready; null if you will poll for the result. For backward compatibility, you may also pass a simple callback URI as a string.
boolean $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)

Inherited Methods

Inherited From Veriplace_AsyncCapableAPI

Veriplace_AsyncCapableAPI::getCallbackResult()
Veriplace_AsyncCapableAPI::getResult()

Class Constants

Inherited Constants

Inherited from Veriplace_AsyncCapableAPI

Veriplace_AsyncCapableAPI::REQUEST_CREATION_BASE_PATH
Veriplace_AsyncCapableAPI::REQUEST_QUERY_BASE_PATH