CrashReporter Scripts

NOTE: This document describes a CrashReporter feature that is currently under development. The current release of CrashReporter, v1.9.1, does not support this functionality.

Overview

CrashReporter provides functionality to ease developers' burden of retrieving information from and performing maintenance on a user's device.

The functionality enables sending a script to a user that, once executed, will gather information from the user's device and generate an email with the information attached, ready to send.

Step 1: Write a Script

A script is a set of instructions that tells CrashReporter to whom the report should be sent and what should be included.

An example script:

# Email a copy of this report to the specified address.
email as "Some Report" to [email protected] is_support

# Include a copy of a file on the user's device.
include as "Some File" file /path/to/file

# Include a copy of a property list on the user's device.
include as "IconState" plist /var/mobile/Library/SpringBoard/IconState.plist

# Include the output of a command (single command).
include as "Package List" command /usr/bin/dpkg -l

# Include the output of a command (script).
include as "Other" command <<EOF
#!/bin/bash

# This is a pointless example.
for i in `seq 1 10`;
do
    echo $i
done    
EOF

The email instruction specifies where the report should be sent, and is required.

The include instruction specifies what to include in (attach to) the report. The instruction supports three types: file, plist, and command.

The include types file and plist both will both include the content of a file. The difference is that the plist type will convert the content of binary property lists to a human-readable format.

The include type command can be used to include the output of either a single command or a script. Only STDOUT is included; to include STDERR, make sure to redirect it to STDOUT. When specifying a script, the begin and end markers ("<<EOF" and "EOF") are required.

Blank lines and lines starting with "#" are ignored. Otherwise, if the line does not begin with a known instruction, the script will be regarded as invalid.

Step 2: Create a URL

Scripts are passed to CrashReporter via the crashreporter:// URL scheme.

There are two forms for passing scripts:

crashreporter://script?data=<Base64 encoded script>
crashreporter://script?url=<URL to script>

The first form allows embedding the script directly into the crashreporter:// URL.

The second form allows for the script to be hosted on a server.

Step 3: Send to User

Send the crashreporter:// URL to the user (via email, IRC, web page, etc.).

Step 4: User Opens URL

Have the user tap the URL on the device that you wish the script to run on.

Step 5: User Reviews and Executes Script

After tapping the URL, CrashReporter will open, download the script (if necessary), and display it for review before processing.

If the user has no objections, they can proceed to execute the script, which will prepare a report with the script result attached.

Step 6: User Sends Report

Once the script has finished executing, the user will be given a chance to review the result and to add any additional feedback to the report.

The user then taps a button to generate an email, which will open in their mail client. Finally, after a final review, they tap send to send the report.