Skip to content

Commit 2ec6de4

Browse files
author
Adam McCarthy
committed
Better instructions for using the SDK
1 parent 9118b84 commit 2ec6de4

File tree

1 file changed

+101
-29
lines changed

1 file changed

+101
-29
lines changed

‎README.md‎

Lines changed: 101 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -21,37 +21,109 @@ Add the Intercom pod into your Podfile and run a `pod install` or `pod update`.
2121
If you get errors, check out our [Troubleshooting section here](http://docs.intercom.io/Install-on-your-mobile-product/install-the-intercom-ios-sdk#-troubleshooting-installation).
2222

2323

24-
## Initialize Intercom
25-
You'll need your Intercom app id and the iOS SDK API key that can be found on the [Intercom App Settings](https://app.intercom.io/) page in the API keys section. Once you've found those keys, initialize Intercom by calling the following in your application's delegate.
26-
27-
[Intercom setApiKey:@"<#ios_sdk-...#>" forAppId:@"<#your-app-id#>"];
28-
29-
## How do I track my users?
30-
31-
In order to see your users in Intercom's user list, you must first register them via your iOS application. If you have a place in your application where you become aware of the user's identity such as a log in view controller, call one of the following depending on the information you have available for that user:
32-
33-
If you have both a unique user identifier and an email for your users:
34-
35-
[Intercom registerUserWithUserId:@"<#123456#>" email:@"<#[email protected]#>"];
36-
37-
If you only have a unique identifier for your users:
24+
##How should I use the Intercom SDK in my app?
25+
Broadly speaking, there are three types of apps that the Intercom SDK will work in.
26+
27+
1. Apps that only have registered users, like Facebook, Instagram or Slack. Your users have to log in straight away in order to use your app.
28+
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.
29+
3. Apps that support both logged in and logged out users, like Google Maps or Youtube.
30+
31+
### Initialize Intercom
32+
No matter what category of app you have, you'll need your Intercom app id and the iOS SDK API key that can be found on the [Intercom App Settings](https://app.intercom.io/) page in the API keys section. Once you've found those keys, initialize Intercom by calling the following in your application delegate:
33+
34+
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
35+
// Initialize Intercom
36+
[Intercom setApiKey:@"<#ios_sdk-...#>" forAppId:@"<#your-app-id#>"];
37+
}
38+
39+
###My app only has logged in users
40+
1. Firstly, on successful completion of your authentication method in your login view controller you will need to register your user.
41+
42+
- (void)successfulLogin {
43+
...
44+
// Registering with Intercom is easy. For best results, use a unique user_id if you have one.
45+
[Intercom registerUserWithUserId:@"<#123456#>"];
46+
}
47+
**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](https://github.com/intercom/intercom-ios/blob/master/Intercom.framework/Versions/A/Headers/Intercom.h#L152)._
48+
49+
2. Also, in your application delegeate's `didFinishLaunchingWithOptions:` method (or wherever you _check_ your user's authenticated state when your app starts up)
50+
51+
// Override point for customization after application launch.
52+
if(loggedIn){
53+
...
54+
// We're logged in, we can register the user with Intercom
55+
[Intercom registerUserWithUserId:@"<#123456#>"];
56+
57+
// Carry on as normal
58+
...
59+
}
60+
}
61+
62+
3. Finally, when users eventually want to log out of your app, we should clear the Intercom SDK's caches so that when they log back in again, everything works perfectly. In your logout code, simply call `[Intercom reset];` like so:
63+
64+
- (void)logout {
65+
...
66+
// This reset's the Intercom SDK's cache of your user's identity and wipes the slate clean.
67+
[Intercom reset];
68+
}
69+
70+
###My apps users never log in
71+
72+
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:
73+
74+
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
75+
...
76+
// This registers an unidentifed user with Intercom.
77+
[Intercom registerUnidentifiedUser];
78+
...
79+
}
80+
81+
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.
82+
83+
###My app has logged in and logged out users
84+
85+
1. Firstly, on successful completion of your authentication method in your login view controller you will need to register your user.
86+
87+
- (void)successfulLogin {
88+
...
89+
// Registering with Intercom is easy. For best results, use a unique user_id if you have one.
90+
[Intercom registerUserWithUserId:@"<#123456#>"];
91+
}
92+
**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](https://github.com/intercom/intercom-ios/blob/master/Intercom.framework/Versions/A/Headers/Intercom.h#L152)._
93+
94+
2. In your application delegeate's `didFinishLaunchingWithOptions:` method (or wherever you _check_ your user's authenticated state when your app starts up)
95+
96+
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
97+
if(loggedIn){
98+
...
99+
// We're logged in, we can register the user with Intercom
100+
[Intercom registerUserWithUserId:@"<#123456#>"];
101+
102+
} else {
103+
// Since we aren't logged in, we are an unidentified user. Lets register.
104+
[Intercom registerUnidentifiedUser];
105+
}
106+
}
107+
108+
3. Finally, when users eventually want to log out of your app, we should clear the Intercom SDK's caches so that when they log back in again, everything works perfectly. In your logout code, simply call `[Intercom reset];` like so:
109+
110+
- (void)logout {
111+
...
112+
// This reset's the Intercom SDK's cache of your user's identity and wipes the slate clean.
113+
[Intercom reset];
114+
115+
// Now that you have logged your user out and reset, you can register a new
116+
// unidentified user in their place.
117+
[Intercom registerUnidentifiedUser];
118+
}
119+
120+
121+
###Tips on getting the best out of the SDK
122+
123+
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](https://github.com/intercom/intercom-ios/blob/master/Intercom.framework/Versions/A/Headers/Intercom.h#L168).
124+
2. The Intercom SDK 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.
38125

39-
[Intercom registerUserWithUserId:@"<#123456#>"];
40126

41-
Finally, if you only have an email address for your users:
42-
43-
[Intercom registerUserWithEmail:@"<#[email protected]#>"];
44-
45-
If you are putting the Intercom SDK into an app that has persisted an authentication token or equivalent so your users don't have to log in repeatedly (like most apps) then we advise putting the user registration call in the `didBecomeActive:` method in your application delegate. This won't have any negative impact if you also add it to your authentication success method elsewhere in your app.
46-
47-
## Can I track unidentifed users?
48-
49-
Yes, absolutely. If you have an application that doesn't require users to log in, you can call:
50-
51-
[Intercom registerUnidentifiedUser];
52-
53-
If the user subsequently logs in or you learn additional information about them (e.g. get an email address), calling any of the other user registration methods will update that user's identity in Intercom and contain all user data tracked previously.
54-
55127
## How does the in-app messenger work?
56128

57129
Intercom allows you to send messages to your users while also enabling your users send messages to you. If you have a dedicated button in your app that you wish to hook the new message composer up to, you can control Intercom's messaging UI via the `[Intercom presentMessageComposer];` and `[Intercom presentConversationList];` methods. More information on messaging with the iOS SDK can be found [here](http://docs.intercom.io/configure-ios-sdk#messaging).

0 commit comments

Comments
 (0)