Wednesday FAQ: Runtime Error Listener

13 March 2013

Wednesday FAQ: Runtime Error Listener

It’s Wednesday and time for another FAQ session. Here are some frequently asked questions (FAQs) about the new runtime error handler and about Android permissions.

1. What about the Runtime Error Message Popup on current Daily Builds?

Starting with Build 1030 on Android and Build 1047 for all other platforms, runtime errors will now generate a popup message box showing the error along with the file and line number (if it’s a debug build). The error information is still displayed in the console, but you don’t need a console/terminal window open to know that an error occurred. Starting with Build 1047, you can include a runtime listener in your code to trap the error and suppress the runtime popup message (if desired).

The runtime message box occurs by default on all platforms, including both the Mac and Windows Simulators.

2. How do I implement a Lua Runtime Error Listener?

The following code shows how to implement the runtime listener (“unhandledError”). If you run the code in the Corona Simulator or on a device, you will see the error caused by concatenating a nil value with a string in the print statement.

If you return false from the listener (the default value), the popup message box occurs when the listener function exits. Returning true indicates that the listener function handled the runtime error and the popup message is suppressed. In the above code, the releaseBuild variable determines if the popup message is displayed or not.

3. What is the best practices for the Runtime Error Listener?

The intent of adding the runtime popup message and the runtime error listener is to give the developer more tools to get there code running and to track down errors. If you build for debug (developer mode on iOS or using the debug key on Android), any runtime errors include the file name and line number where the error occurred. It also includes a message about the error. Normally, this information is included in the popup message box. If you add the runtime listener and suppress the popup, you still have access to the error information through the event table passed to the listener and in the console/terminal.

In production release, only the error type is available. You can implement the runtime listener and use it to suppress the error popup and log the errors internally. What you do with this error log is up to you. You can ignore it or create a log file that is sent to your own server to track problems. One of the advantages of allowing popup errors to occur, is that it sends the information back to Google Play, which makes the information available to the developer. If you suppress the popup, the information will be lost unless you log and send it to your own server.

You may want to allow the runtime popups during your debug and testing phases and suppress the popup when you deliver your app to the app store.

One thing that I mentioned in a previous FAQ, ignoring errors is not the best practice. Runtime errors will alter the code path and may cause the app to become unstable. You should always test your app on as many devices as possible and eliminate or trap (using pcall) any errors found.

4. I’m using the Runtime Listener but I’m still getting the Runtime Error popup.

If you implemented the runtime error listener in your code that suppresses the error popup and you’re still getting the popup, you may have an error occurring before the runtime listener starts. As shown in the above example code, the runtime listener function was the first thing defined in the code. The key is enabling the runtime listener as soon as possible so it can trap the errors. Errors that occur before the runtime error listener has been enabled, will generate the popup message. Generally, errors that occur on startup are easy to fix and don’t require trapping. It’s the runtime errors that occur with touch events, collisions, etc., that occur while the app is running, that are the important ones to trap if you want to suppress the popup message to your users.

5. What about Android Permissions and runtime errors?

In Build 1030 we removed the default permissions in the Android Manifest so you are now responsible for adding back the permissions for APIs that require them. All the Daily Build sample code projects and the API pages have been updated to show the required permissions in the build.settings file.

Generally, missing permissions will generate a runtime error with either a runtime popup or by calling the runtime “unHandledError” listener (if implemented). Missing permissions is something that should be tested and caught before releasing your app (see question 6).

6. Which Android Permissions won’t generate a runtime error?

Some API calls will fail silently if the proper permissions are not set in build.settings file. They are:

• display.capture
• display.captureBoard
• display.captureScreen
• media.newRecording
• media.newVideo
• media.save
• media.show
• native.webView
• native.newWebPopup
• heading( Compass) event
• location (GPS) event

For the APIs listed above, you need to check the results to verify that the code works as expected. It’s a good idea to double check that you have set the proper permissions in the build.settings file for those APIs. For future builds we are looking at adding runtime checks for all APIs to insure they all have the proper permissions set.

Check the Daily Build Documents for the correct Android permissions needed for each API.

That’s it for today’s answers. I hope you enjoyed them and even learned a few things!