Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Extra debugging information for iOS SDKs

Some Twilio's client iOS SDKs distribute dSYM files along side the framework for our downloads. dSYM files (debug symbol files) contain information Apple's crashlog symbolicator and third party crash reporting services such as Fabric's Crashlytics or HockeyApp use to reintroduce debug information typically optimized out during the build process.

Providing Twilio support with crash logs processed with this extra debugging information can greatly enhance our ability to help diagnose and address such issues.

If you are using CocoaPods 1.3.0 or later, you're in luck! CocoaPods 1.3.0 introduced the ability to include vendored dSYM files (like those Twilio ships) in the archives you generate in Xcode automatically. This helps the Apple AppStore as well as services such as HockeyApp to provide more robust crashlogs to you. These dSYM files are also available for services such as Fabric's Crashlytics with an additional custom script step in your build process. Last but not least, these dSYM files are useful to you to use locally when symbolicating crashes either at development time or after the fact using Apple's command line tools.

We'll be discussing the most common path we see with our customers for integration, CocoaPods along with Fabric's Crashlytics, below. Regardless of what reporting solution you use, the dSYM files will be invaluable in providing more detail in diagnosing any crashes that may occur involving our SDKs.


To take advantage of automatic dSYM bundling, we recommend you use CocoaPods 1.3.0 or newer. This version of CocoaPods added detection and bundling of dSYM files for vendored frameworks. Embedding dSYM files for the Twilio SDKs you use is as easy as using CocoaPods 1.3.0 or later along with a version of the Twilio iOS SDK that ships the dSYM's. Be sure to check the Changelog for the SDK you are interested in to see which versions include bundled dSYM support.

When you archive your project for shipping to the AppStore, HockeyApp, or another distribution mechanism you will find the supported Twilio SDKs dSYM files along side your application's dSYM file in the dSYMs directory of the archive. If you are using the AppStore's built-in crash reporting or HockeyApp your work is done.

Uploading dSYM files to Fabric's Crashlytics

If you are integrating Fabric's Crashlytics, there is one additional step to perform. After your call to Fabric's run shell script, you'll want to add an additional Run Script Phase to the Build Phases for your target(s) with the following content:

find ${DWARF_DSYM_FOLDER_PATH} -name "*.dSYM" | xargs -I \{\} "${PODS_ROOT}/Fabric/upload-symbols" -a <fabric-api-key> -p ios \{\}

Your fabric-api-key is likely the first parameter of your existing run script phase if you have Fabric integrated. You can also find it on your Fabric Organziation's page. If you need assistance integrating Fabric, you can find more information here.

This will locate all of your vendored dSYM files for the current build and upload them to Fabric. The run shell script phase takes care of your main application's dSYM file but this ensures you shouldn't run into any "Missing DSYMs" in Fabric's console for your application for any vendored dSYM files.

Extended diagnostic details for Fabric Crashlytics users

Crashlytics has the ability for applications to provide extra details that will accompany crash reports should a crash occur. This extra information comes in the form of Keys, Logs, and Identifiers. We recommend customers exercise care in the information submitted to any third party to protect user's privacy as well as adhere to regulations around how such information is used. One piece of information we find helpful in particular for customers to set is the version of each Twilio SDK you use. Including the version for the Twilio SDKs you integrate helps to narrow down possible root causes. Here is an example of providing version information for our Programmable Chat SDK. You should run this sometime after you have initialized Fabric within your application, but before you use the Twilio SDK for the first time:

[CrashlyticsKit setObjectValue:[TwilioChatClient sdkVersion] forKey:[TwilioChatClient sdkName]];

With this Key set, the version of the Programmable Chat for iOS client will be included in any crash reports for your application. The presence and name of the sdkName and sdkVersion properties may differ between Twilio SDKs but most that have dSYM files provided within the SDK will have these properties available.

You can learn more about enhancing crash reports on Fabric's website.

Additional information

Twilio client SDK's for iOS that ship with dSYM files typically will do so in the following manner:

  • At the root of the .tar.bz2 file you download, you will find the TwilioProductClient.framework file
  • In the same directory will be a TwilioProductClient.framework.dSYM bundle
  • Additionally you will find a TwilioProductClient.framework.dSYM.txt file containing the identifying UUID's for each architecture included in the client SDK specific to this build of the framework

The .txt file can be useful for locating a missing dSYM archive by UUID (for example, on the Crashlytics Missing DSYMs tab).

To upload a dSYM after-the-fact to Crashlytics, you can either use the command line interface or compress the .dSYM package as a .zip file and upload it using Fabric's web interface.

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.

Loading Code Sample...