Use the scratchpad below to test various API configurations for the Picup iOS app.
Choose a Version:
The latest version of Picup is 2.4, which accepts params unrecognized by version 1.
Versions 1 and 2+ have different URL schemes to avoid conflicts, but future updates will be managed with the "minRequiredVersion" parameter. It's recommended that you use the lowest version that meets your needs.
Choose an Action:
Parameters listed below apply to the selected action.
Specifies how Picup will format the return params to your callback URL. If value is "query" or null, they will be appended as a query string. If "hash" is specified, the values will be appended as a hash string. Both are key-value-pairs separated by ampersands.
If this parameter is specified, Picup will open this URL if the user cancels the file upload. It will be opened by whatever app handles the URL scheme (e.g. Safari will open http:// URLs). No callback data is appended to this URL.
Possible Values
Any escaped URL
Default Value
null
Sample Value
"http%3A//mysite.com/cancelled.html" OR
"customscheme%3A//customurl"
Minimum Version Required
2.1
Discussion
Default Behavior
If a cancelURL is not specified, the user will stay in Picup once the file upload is cancelled.
Callback Application & Browser Compatibility
The cancelURL can be used to open webapps or native apps via a custom URL scheme. However, at time of this writing, iOS doesn't support launching a stand-alone webapp from the springboard. All URLs using the http[s] scheme will be opened in Mobile Safari.
If the web form is loaded in a browser other than Mobile Safari, the Picup JavaScript helper automatically changes the cancel URL scheme so control is returned to the app which Picup was called from. For example, if the client is Google Chrome, the cancelURL will be changed to googlechrome://mysite.com/cancelled.html. Supported browsers are Safari, Chrome and Opera. To disable this behavior, set Picup2.shouldConvertCallbackURLScheme = false;
If this parameter is specified, Picup will open this URL when the transaction is complete. It will be opened by whatever app handles the URL scheme (e.g. Safari will open http:// URLs). Generally speaking this is the way to return control to your app with details about the upload.
Possible Values
Any escaped URL
Default Value
null
Sample Value
"http%3A//mysite.com/success.html" OR
"customscheme%3A//customurl"
Minimum Version Required
1.0
Discussion
Param Type in the callback URL
Because the return values can be very long, the default behavior is to
append them to the the callbackURL as a hash value, not a query string
(e.g. http://myapp.com/upload_complete#foo=bar&status=Complete).
This allows Picup to circumvent some web
server URL length limits.
Version 2 allows you to choose the callback param type with callbackParamType.
Callback Window
If the URL uses the "http://" scheme, Picup will open a new window
in Safari rather than returning control to the window that launched it.
For this reason, it is recommended that the callback page be transient,
rather than opening a second copy of the first window. Please read
Design Patterns & Best Practices for more information.
Callback Params
See the returnStatus discussion for a list of params that might be returned.
Callback Application & Browser Compatibility
The callbackURL can be used to open webapps or native apps via a custom URL scheme. However, at time of this writing, iOS doesn't support launching a stand-alone webapp from the springboard. All URLs using the http[s] scheme will be opened in Mobile Safari.
If the web form is loaded in a browser other than Mobile Safari, the Picup JavaScript helper automatically changes the callback URL scheme so control is returned to the app which Picup was called from. For example, if the client is Google Chrome, the callbackURL will be changed to googlechrome://mysite.com/success.html. Supported browsers are Safari, Chrome and Opera. To disable this behavior, set Picup2.shouldConvertCallbackURLScheme = false;
Escape Characters
If your callbackURL contains escaped characters, you must double escape them. For example http://mysite.com/callback%20complete.html is double escaped to http://mysite.com/callback%2520complete.html. Basically, just replace all occurrences of % with %25.
The longest dimension of the image uploaded to the server.
Possible Values
Any integer
Default Value
Version 1:800 Version 2:null (or 800 for uploads to imgur)
Sample Value
450
Minimum Version Required
1.0
Discussion
Leaving this value blank (or 0) will upload the original file. However, if the postURL is also blank (and the image is uploaded to imgur), the image will be scaled to 800px.
If this value is true, the user will only be able to select and upload 1 file at a time. If the value is false or null, the user will be allowed to make multiple uploads. Regardless of which option is selected, the files will be uploaded as atomic requests to the host server. However, restricting the number of uploads may be desirable if the parameters include unique values for individual files.
Possible Values
true or false (null)
Default Value
false
Sample Value
true
Minimum Version Required
2.0
Discussion
If Picup is called with the version 1 API, this value is automatically set to true.
If this value is not null (or 0) file upload will be limited to files that are smaller than the specified value (in bytes).
Possible Values
Any integer
Default Value
null
Sample Value
15000
Minimum Version Required
2.0
Discussion
In the case of images, Picup measures the original file before it's resized. For higher-resolution control over image size, consider using the imageSize param.
The minimum version of Picup that is required by your upload form.
Possible Values
Any integer or decimal number
Default Value
null
Sample Value
2.0
Minimum Version Required
2.0
Discussion
If the minimum app version has not been downloaded, the user will be required to update before they can upload a file. This may be useful if your interface depends upon newer features, such as video upload. NOTE: This param is not recognized by Picup v.1 and should only be used with the new url scheme (fileupload2://).
The parameter name of the file POSTed to the server. This is useful if you're using a server other than imgur, but should not be changed if you're using the default postURL.
Possible Values
Any string
Default Value
"file"
Sample Value
"uploadData"
Minimum Version Required
2.0
Discussion
This param was previously named postImageParam (in Version 1.0).
Depreciated. Param has been renamed postFileName in version 2.
Description
The filename of the image POSTed to the server.
Possible Values
Any string
Default Value
Version 1: Determined by timestamp (e.g. "20100129132234.jpg") Version 2: A globally unique identifier (e.g. "12874CE3-61E4-4A07-B16B-24D1F7C5541C.jpg")
Depreciated. Param has been renamed postFileParamName in version 2.
Description
The parameter name of the image POSTed to the server. This is useful if you're using a server other than imgur, but should not be changed if you're using the default postURL.
These parameters will be POSTed to the upload server along with the image. This is useful if you are using a server other than imgur and you need to pass along information such as a user_id or API Key. Passing in ANY value for this parameter will override the default imgur API key.
Possible Values
Any escaped string of parameters formatted as a GET query string.
Informs the user what the image request will be used for. This is useful in the case that an upload is unsuccessful (e.g. offline usage) and the user later resumes the upload.
This favicon for the App requesting a file upload. This is displayed in the context of a specific upload.
Possible Values
The escaped URL of a favicon.ico file, or a favicon in data:URL format (escaped).
Default Value
The imgur favicon
Sample Value
Minimum Version Required
1.0
"http%3A//www.google.com/favicon.ico" OR "data%3A%3Bbase64%2CAAABAAEAEBAAAAAAAABoBQAAFgAAACgAAAAQAAAAIAAAAAEACAAAAAAAAAEAAAAAAAAAAAAAAAEAAAAAAAAAAAAA148EAP///wDUjQQAooNMAMiGAADTiwQA56QAANGJBADSkQAAwH4AAO7SngD/vAAA3JoAAN2aAADWjgQAyIcAANSMBAD5tgAA6KUAANGQAAC/fwAA0pAAAMB/AADcmwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQEBAQEBAQEBAQEBAQEAAQXFxcKFxcKFwoVFxcKFwQEEAUFEAUQEAUQBQUFEAUEBBYWFhYWFhYWFhYJFgkUBAQIDQ0ICAgOCA0YCAgIDgQEBgIGEwILAgYCBgcCCwIEBBECEQIPAwIRAhECDxECBAQPAhICDw8CDwISAg8PAgQEAQIMDAICAgECDAwCAgIEBAECDAwMDAwBAgwMDAwMBAQMAgwMDAwMDAIMDAwMDAQEDAwMDAwMDAwMDAwMDAwEBAwMDAwMDAwMDAwMDAwMBAQMDAwMDAwMDAwMDAwMDAQEDAwMDAwMDAwMDAwMDAwEAAQEBAQEBAQEBAQEBAQEAIABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAIABAAA%3D"
Determines if Picup should return information about the upload request as callback parameters.
Possible Values
true (null) or false
Default Value
true
Sample Value
false
Minimum Version Required
1.0
Discussion
Callback Params
With the exception of debug, these params will only be returned if the returnStatus request param is true. Possible callback params include:
debug
Returns true if the request URL was called with debug=true. See the debug request parameter for more info.
fileSource (version 2)
A description of the file source (e.g. "Photo Library" or "Dropbox").
remoteImageURL (version 1)
The location of the image if it was uploaded to imgur.
remoteFileURL (version 2)
The location of the file if it was uploaded to imgur.
picID
The unique identifier of the file, which can be used to view the file in Picup using the "view" action.
serverResponse
The entire text response from the server. Note, this is not the HTTP status.
status
A description of the upload status (e.g. "Incomplete", "Complete"). Note, this is not the HTTP status.
thumbnailDataURL
A dataURL containing the thumbnail image of the upload in png format.
Param Format: Version 2+
As of version 2, params are returned in array notation regardless of how many files have been uploaded. After escaping and formatting, the params might look like this:
Passing in a unique identifier will save the configuration as a "Destination." Saving a Destination allows users to upload to your server directly from the app without having to visit your mobile website. The values of a previously saved Destination will be updated if the stored values dont match the values passed in by subsequent uploads.
Possible Values
An escaped string shorter than 100 characters
Default Value
null
Sample Value
"com.mycompany.avatar_upload"
Minimum Version Required
2.0
Discussion
In the iOS database, these unique identifiers are prepended with the POST server domain for security reasons. Changing the domain of the postURL will create a new Destination even if the identifier is the same as an existing Destination.
If the value is true, the EXIF metadata will be appended to the image file. If the user grants access to location services, their Latitude and Longitude will be included in this metadata.