Inter-App Callbacks

 

About

Inter-app communication, or IAC, is a framework that allows your app to communicate with ProntoForms installed on your mobile device, as long as it supports the x-callback-url protocol. ProntoForms supports this protocol. This article will discuss the parameters, error codes, and best practices for using the x-callback-url protocol with ProntoForms.

More general information on inter-app communication is available in our Inter-App Communication and Inter-App Dispatch articles. 

[ top ]

 

Custom URL Scheme

The custom URL scheme is the part of the link that tells your device what protocol to use when you click a ProntoForms link in another (external) app. This forms the basis for inter-app calls.

Example:

prontoforms://
https://prontofor.ms/

The  custom URL Scheme (prontoforms://) is of more interest to app developers, but does not work through browsers or via the Android SMS configuration. However, it is more secure than the custom inter-app hostname (https://prontofor.ms).

[ top ]

 

 

X-Callback Parameters

 ProntoForms uses the x-callback-url specification to control what happens after actions are triggered within the Inter-App Call URL. As follows: 

 

Action Parameter Description Type Expected Values
 x-cancel This is the URL that is opened when the requested action is cancelled, e.g. tapping the Back button on Android, thereby discarding the form that was opened via interapp call. string user-defined
x-success

If the action in the target method is intended to return a result to the source app, the x-callback parameter should be included and provide a URL to open to return to the source app. On completion of the action, the target app will open this URL. If x-success is not provided, it is assumed that the user will stay in the target app on successful completion of the action.

Additional parameters that may be appended to the URL for the open action: clientDataRecordID if the form was saved as a draft, and serverDataRecordID if the form was completed and sent.

Adding the x-success parameter into your ProntoForms URL action tells ProntoForms to perform the next action upon the success of the first one. That is, once the first action is completed, the next one will be run. Since this depends upon the success of the first action, remember that your second action will never be run if the first one fails. This is why testing and re-testing each part of your URL actions is important. Your second action could be typed up perfectly, but if the first one has a slight error that causes it to fail, the second will never get a chance.

 string user-defined
x-error

When used in conjunction with the action parameter, this URL will be opened if the action generates an error and cannot be completed successfully.

string user-defined

 

[ top ]

 

 

Error Codes and Messages

ProntoForms has a number of defined error codes. As follows: 

PFErrorCodeListNotFound / 2001
if the request is
prontoforms://x-callback-url/list 
prontoforms://x-callback-url/list?type=forms
Error message: Form list not found.

if the request is
prontoforms://x-callback-url/list?type=inbox
Error message: Inbox not found.

if the request is
prontoforms://x-callback-url/list?type=sent
Error message: Sent list not found.

 

PFErrorCodeItemNotFound / 1010
if the request is
prontoforms://x-callback-url/open?formID=15872001
A form with the requested ID does not exist. FormID = 15872001

if the request is
prontoforms://x-callback-url/open? formIterationID=15872001
A form with the requested iteration ID does not exist. FormIterationID = 15872001

prontoforms://x-callback-url/open?formName=Inspection 
A form with the requested name does not exist. FormName = Inspection

if the request is
prontoforms://x-callback-url/open?DataRecordID=15872001
A Data Record with the requested ID does not exist. DataRecordID = 15872001

if the request is
prontoforms://x-callback-url/open?clientDataRecordID=15872001
A Data Record with the requested local data record ID does not exist. ClientDataRecordID = 15872001

if the request is
prontoforms://x-callback-url/list?type=inboxList
Error message: A list that is named “inboxList“ does not exist.

 

More will be added in future.

[ top ]

 

Best Practices

Security

If you are concerned about security, it is best to use the following format for your inter-app callbacks:

prontoforms://x-callback-url/list?type=inbox&x-success=customapp://x-callback-url&x-cancel=customapp://x-callback-url&x-error=customapp://x-callback-url

Ensure all Outcomes have Parameters

If you have a success, add a /success/<parameters> into the URL to show the outcome of your inter-app call. This should be done for all the action parameters.

[ top ]

 

Diagrams and Examples

 2017-09-12-InterAppCall-Launch.png

 

2017-09-13-InterAppCall-OpenUniqueForm.png

 

 

[ top ]

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments