The Intercom iOS library supports iOS 7.x and upwards.

Installing Intercom

There are two ways to install Intercom on your iOS app:

Using cocoapods

  1. Add the Intercom pod into your Podfile like so:
  2. pod 'Intercom'
  3. Do a pod update or a pod install.

Manual Install

  1. Download Intercom for iOS and use Finder to drag Intercom.framework and Intercom.bundle into your Xcode project, ticking the "Copy items if needed" checkbox.

If you get errors after installation, check out our Troubleshooting section below.

How to use Intercom in your app

Broadly speaking, there are three types of apps that Intercom will work in.

  1. Apps that have only registered users, like Facebook, Instagram or Slack. Your users have to log in straight away in order to use your app.
  2. Apps that never log users in, like Threes Game or Angry Birds or the iOS Notes app. Your users never have to log in to use your app.
  3. Apps that support both logged in and logged out users, like Google Maps or Youtube.

Initialize Intercom

No matter what category of app you have, you'll need your Intercom app id and the iOS API key that can be found on the Intercom App Settings page in the API keys section. Once you've found those keys, initialize Intercom by calling the following in your application delegate:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Initialize Intercom
    [Intercom setApiKey:@"" forAppId:@""];
}

My app only has logged in users

  1. Firstly, on successful completion of your authentication method in your login view controller you will need to register your user.
    - (void)successfulLogin { 
        ...
        // Registering with Intercom is easy. For best results, use a unique user_id if you have one.
        [Intercom registerUserWithUserId:@"<#123456#>"];
    }
    Note:If you don't have a unique userId to use here, or if you have a userId and an email you can register with those too.

  2. Also, in your application delegeate's didFinishLaunchingWithOptions: method (or wherever you check your user's authenticated state when your app starts up)
    // Override point for customization after application launch.
        if(loggedIn){
            ...
            // We're logged in, we can register the user with Intercom
            [Intercom registerUserWithUserId:@"<#123456#>"];
            // Carry on as normal
            ...
        }
    }
  3. Finally, when users eventually want to log out of your app, we should clear Intercom's caches so that when they log back in again, everything works perfectly. In your logout code, simply call [Intercom reset]; like so:
    - (void)logout {
        ...
        // This reset's Intercom's cache of your user's identity and wipes the slate clean.
        [Intercom reset];
    }

My apps users never log in

  1. If you only have unidentifed users in your app then your integration is only one line. Just register an unidentified user in your application's delegate like so:
    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
        ...
        // This registers an unidentifed user with Intercom.
        [Intercom registerUnidentifiedUser];
        ...
    }
    Because Intercom listens for UIApplication start notifications, there is no need to have this line of code anywhere else. Intercom will track all of your user sessions for you.

My app has both logged in and logged out users

  1. Firstly, on successful completion of your authentication method in your login view controller you will need to register your user.
    - (void)successfulLogin { 
        ...
        // Registering with Intercom is easy. For best results, use a unique user_id if you have one.
        [Intercom registerUserWithUserId:@"<#123456#>"];
    }
    Note:If you don't have a unique userId to use here, or if you have a userId and an emailyou can register with those too.

  2. In your application delegate's didFinishLaunchingWithOptions: method (or wherever you check your user's authenticated state when your app starts up)
    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
        if(loggedIn){
            ...
            // We're logged in, we can register the user with Intercom
            [Intercom registerUserWithUserId:@"<#123456#>"];
        } else {
            // Since we aren't logged in, we are an unidentified user. Lets register.
            [Intercom registerUnidentifiedUser];
        }
    }
  3. Finally, when users eventually want to log out of your app, we should clear Intercom's caches so that when they log back in again, everything works perfectly. In your logout code, simply call [Intercom reset]; like so:
    - (void)logout {
        ...
        // This reset's Intercom's cache of your user's identity and wipes the slate clean.
        [Intercom reset];
        // Now that you have logged your user out and reset, you can register a new
        // unidentified user in their place.
        [Intercom registerUnidentifiedUser];
    }

Tips on getting the best out of your installation

  1. Do not use an email address as a userId as this field is unique and cannot be changed or updated later. If you only have an email address, you can just register a user with that. More details are available here.
  2. If you register users with an email address then email must be a unique field in your app. Otherwise we won't know which user to update and the mobile integration won't work.
  3. Intercom listens for when your app starts and stops, so all you need to do is register a type of user like the examples above and we'll do the rest.

Troubleshooting tips

  1. If the iOS keyboard does not respond properly to rotation events on iPhone 6 and iPhone 6 Plus: there is a known issue in iOS 8.x for apps that scale their UIs rather than natively supporting those new screen sizes. If the app does support landscape and portrait orientations, but the view controller that is shown when the Intercom Messenger is opened does not allow rotation (by implementing the supportedInterfaceOrientations method), sometimes the keyboard positioning breaks on rotation. This can be fixed by supporting the iPhone 6 and 6 Plus screen sizes.

What next?

Once you've got Intercom installed it's time to configure it for your product. You also find the Intercom docset in the github repository.

Did this answer your question?