Skip to content

Commit 14df712

Browse files
vbabenkoruvbabenkoru
authored
Merge pull request #49 from Iterable/feature/ITBL-5303-sdk-updates-docs
[ITBL-5303] Update documentation with recent SDK changes
2 parents 56831b3 + ef273be commit 14df712

File tree

2 files changed

+162
-38
lines changed

2 files changed

+162
-38
lines changed

‎CHANGELOG.md

+33-2
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,39 @@ This project adheres to [Semantic Versioning](http://semver.org/).
1515
#### Fixed
1616
- nothing yet
1717

18+
## [3.0.0](https://github.com/Iterable/iterable-android-sdk/releases/tag/3.0.0)
19+
_Released on 2018-07-26_
20+
#### Added
21+
- Full FCM support
22+
- Added support for push action buttons
23+
- Added a new SDK initialization method that takes `IterableConfig` object with configuration options
24+
- User ID/email is now decoupled from SDK initialization. It can be changed by calling `setEmail` or `setUserId` on the `IterableApi` instance.
25+
- The SDK now stores attribution data within 24 hours of opening the app from a push notififcation or from an App Link in an email
26+
- Added two handlers: `IterableUrlHandler` and `IterableCustomActionHandler` that can be used to customize URL and custom action handling for push notifications
27+
28+
#### Removed
29+
- Removed GCM support
30+
31+
#### Changed
32+
- Old initialization methods (`sharedInstanceWithApiKey`) are now deprecated
33+
- Old `registerForPush` and `registerDeviceToken` methods are now deprecated
34+
35+
#### Migration Notes
36+
1. If you're using GCM, update your Android app to Firebase Cloud Messaging
37+
2. Replace `IterableAPI.sharedInstanceWithApiKey(...)` with the following:
38+
```java
39+
IterableConfig config = new IterableConfig.Builder()
40+
.setPushIntegrationName("myPushIntegration")
41+
.setUrlHandler(this) // If you want to handle URLs coming from push notifications
42+
.build();
43+
IterableApi.initialize(context, "YOUR API KEY", config);
44+
```
45+
3. Call `registerForPush()` to retrieve the push token and register the device.
46+
4. User email/userId is now persisted, so you'll only need to call `setEmail` or `setUserId` when the user logs in or logs out.
47+
5. The SDK now tracks push opens automatically, as long as the SDK is initialized in `Application`'s `onCreate`. See README for instructions. Once it is set up, remove all direct calls to `trackPushOpen`.
48+
1849
## [2.2.5](https://github.com/Iterable/iterable-android-sdk/releases/tag/2.2.5)
19-
_Released on 2017-03-31_
50+
_Released on 2018-03-31_
2051

2152
#### Changed
2253
- Updated requests to not send when there is an exception while constructing the JSON request body.
@@ -25,7 +56,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
2556
- Fixed the reference to internal fields in NotificationCompat.Builder for buildVersion 27.
2657

2758
## [2.2.4](https://github.com/Iterable/iterable-android-sdk/releases/tag/2.2.4)
28-
_Released on 2017-03-07_
59+
_Released on 2018-03-07_
2960

3061
#### Fixed
3162
- Fixed the load sequence for retrieving a notification image.

‎README.md

+129-36
Original file line numberDiff line numberDiff line change
@@ -1,76 +1,169 @@
11
# Iterable Android SDK
22

3-
The `iterable-android-sdk` is a java implementation of an android client for Iterable, supporting api versions 15 and higher.
3+
The `iterable-android-sdk` is a Java implementation of an Android client for Iterable, supporting Android API versions 15 and higher.
44

5-
## Setting up a push integration in Iterable
5+
# Setting up a push integration in Iterable
66

77
Before you even start with the SDK, you will need to:
88

99
1. Set your application up to receive push notifications, and
10-
2. Set up a push integration in Iterable. This allows Iterable to communicate on your behalf with Google's Push Notification Service.
10+
2. Set up a push integration in Iterable. This allows Iterable to communicate on your behalf with Firebase Cloud Messaging.
1111

12-
For information on setting up your Google Api Project, see
12+
For information on setting up your Firebase Project, see
1313

14-
* [Configuring Push Notifications](http://docs.aws.amazon.com/sns/latest/dg/mobile-push-gcm.html)
14+
* [Add Firebase to Your Android Project](https://firebase.google.com/docs/android/setup)
1515

16-
To setup your push integration with Iterable in the web dashboard go to `Integrations -> Mobile Push`. When creating an integration, you will need to pick a name and a platform. The name is entirely up to you; it will be the `applicationName` when you use `registerForPush` or `registerDeviceToken` in our SDK.
16+
To setup your push integration with Iterable in the web dashboard go to `Integrations -> Mobile Push`. When creating an integration, you will need to pick a name and a platform. The name is entirely up to you; it will be the `pushIntegrationName` in `IterableConfig` when you initialize our SDK.
1717

18-
The platform will be `GCM` (This also includes FCM since it runs off of GCM). Add the Api server key (If on FCM use the Legacy Server Key).
18+
The platform will be `GCM` (This also includes FCM since it runs off of the same infrastructure). Add the Firebase Cloud Messaging Server Key obtained from the Firebase console.
1919

2020
![Creating an integration in Iterable](https://support.iterable.com/hc/en-us/article_attachments/211841066/2016-12-08_1442.png)
2121

2222
Congratulations, you've configured your mobile application to receive push notifications! Now, let's set up the Iterable SDK...
2323

24-
## Automatic Installation
24+
# Installing the SDK
25+
26+
Add the following dependencies to your application's `build.gradle`:
27+
28+
```groovy
29+
compile 'com.iterable:iterableapi:3.0.0'
30+
compile 'com.google.firebase:firebase-messaging:X.X.X' // Min version 9.0.0
31+
```
2532

2633
See [Bintray](https://bintray.com/davidtruong/maven/Iterable-SDK) for the latest version of the Iterable Android SDK.
2734

28-
## Additional Information
35+
# Using the SDK
2936

30-
See our [setup guide](https://support.iterable.com/hc/en-us/articles/115000331943-Setting-up-Android-Push-Notifications) for more information.
37+
1. On application launch (ideally, in `Application`'s `onCreate`), initialize the Iterable SDK:
3138

32-
Also see our [push notification setup FAQs](http://support.iterable.com/hc/en-us/articles/206791196-Push-Notification-Setup-FAQ-s).
39+
```java
40+
IterableConfig config = new IterableConfig.Builder()
41+
.setPushIntegrationName("myPushIntegration")
42+
.build();
43+
IterableApi.initialize(context, "<your-api-key>", config);
44+
```
45+
46+
* The `apiKey` should correspond to the API key of your project in Iterable. If you'd like, you can specify a different `apiKey` depending on whether you're building in `DEBUG` or `PRODUCTION`, and point the SDK to the relevant Iterable project.
47+
* Ideally, you will call this from `Application`'s `onCreate`. This will let the SDK automatically track a push open for you if the application was launched from a remote Iterable push notification.
48+
49+
2. Once you know the email *(Preferred)* or userId of the user, call `setEmail` or `setUserId`
50+
* EMAIL: `IterableApi.getInstance().setEmail("[email protected]");`
51+
* USERID: `IterableApi.getInstance().setUserId("userId");`
52+
* If you are setting a userId, an existing user must already exist for that userId
53+
* It is preferred that you use Email since that doesn't require an additional lookup by userId call on the backend.
54+
55+
3. **Register for remote notifications**
56+
On application launch (or whenever you want to register the token), call `registerForPush`:
57+
58+
```
59+
IterableApi.getInstance().registerForPush();
60+
```
3361
34-
##Optional Setup
62+
This will take care of retrieving the token and registering it with Iterable.
63+
> &#x26A0; Device registration will fail if user email or userId is not set. If you're calling `setEmail` or `setUserId` after the app is launched (i.e. when the user logs in), make sure you call `registerForPush()` again to register the device with the logged in user.
64+
65+
Congratulations! You can now send remote push notifications to your device from Iterable!
3566
36-
### Firebase Messaging
37-
At this time there is no requirement to upgrade to FCM since Google will continue to support current versions of GCM android.
3867
39-
If you want to use using Firebase Cloud Messaging (FCM) instead of Google Cloud Messaging (GCM) pass in `IterableConstants. MESSAGING_PLATFORM_FIREBASE` as the pushServicePlatform.
68+
#### Disabling push notifications to a device
69+
70+
When a user logs out, you typically want to disable push notifications to that user/device. This can be accomplished by calling `disablePush()`. Please note that it will only attempt to disable the device if you have previously called `registerForPush()`.
71+
72+
In order to re-enable push notifcations to that device, simply call `registerForPush()` as usual when the user logs back in.
73+
74+
#### InApp Notifications
75+
To display the user's InApp notifications call `spawnInAppNotification` with a `IterableActionHandler` callback handler. When a user clicks a link in the notification, the handler is called and passed the URL defined in the InApp template.
76+
77+
InApp opens and button clicks are automatically tracked when the notification is called via `spawnInAppNotification`. Using `spawnInAppNotification` the notification is consumed and removed from the user's in-app messages queue. If you want to retain the messages on the queue, look at using `getInAppMessages` directly. If you use `getInAppMessages` you will need to manage the in-app opens manually in the callback handler.
78+
79+
#### Tracking and Updating User Fields
80+
81+
Custom events can be tracked using the `track` function and user fields can be modified using the `updateUser` function.
82+
83+
84+
# Deep Linking
85+
#### Handling links from push notifications
86+
Push notifications and action buttons may have `openUrl` actions attached to them. When a URL is specified, the SDK first calls `urlDelegate` specified in your `IterableConfig` object. You can use this delegate to handle `openUrl` actions the same way as you handle normal deep links. If the delegate is not set or returns NO, the SDK will open Safari with that URL.
4087
4188
```java
42-
public void registerForPush(String iterableAppId, String projectNumber, String pushServicePlatform) {
89+
// MyApplication.java
90+
91+
@Override
92+
public void onCreate() {
93+
super.onCreate();
94+
...
95+
IterableConfig config = new IterableConfig.Builder()
96+
.setPushIntegrationName("myPushIntegration")
97+
.setUrlHandler(this)
98+
.build();
99+
IterableApi.initialize(context, "YOUR API KEY", config);
100+
}
101+
102+
@Override
103+
public boolean handleIterableURL(Uri uri, IterableActionContext actionContext) {
104+
// Assuming you have a DeeplinkHandler class that handles all deep link URLs and navigates to the right place in the app
105+
return DeeplinkHandler.handle(this, uri);
106+
}
43107
```
44108

45-
**Note**: If you are upgrading to FCM, do not downgrade back to GCM as this will cause devices to be registered for notifications twice and users will get duplicate notifications.
109+
#### Handling email links
110+
For App Links to work with link rewriting in emails, you need to set up apple-assetlinks.json file in the Iterable project. More instructions here: [Setting up Android App Links](https://support.iterable.com/hc/en-us/articles/115001021063-Setting-up-Android-App-Links)
46111

47-
### InApp Notifications
48-
To display the user's InApp notifications call `spawnInAppNotification` with a defined `IterableActionHandler` callback handler. When a user clicks a button on the notification, the defined handler is called and passed the action name defined in the InApp template. If no action is defined, the callback handler will not be called.
112+
If you already have a `urlDelegate` (see *Handling links from push notifications* section above), the same handler can be used for email deep links by calling `handleAppLink` in the activity that handles all app links in your app:
49113

50-
InApp opens and button clicks are automatically tracked when the notification is called via `spawnInAppNotification`. `spawnInAppNotification` automatically consumes and removes the notification from the user's list of pending notification. If you do not want to remove the notification use `getInAppMessages` & `IterableInAppManager.showNotification` instead.
114+
```java
115+
// MainActivity.java
116+
@Override
117+
public void onCreate() {
118+
super.onCreate();
119+
...
120+
handleIntent(getIntent());
121+
}
51122

52-
### Deeplinking
123+
@Override
124+
public void onNewIntent(Intent intent) {
125+
super.onNewIntent(intent);
126+
if (intent != null) {
127+
handleIntent(intent);
128+
}
129+
}
53130

54-
See our [Deeplinking Setup Guide] (https://support.iterable.com/hc/en-us/articles/211676923)
131+
private void handleIntent(Intent intent) {
132+
if (Intent.ACTION_VIEW.equals(intent.getAction()) && intent.getData() != null) {
133+
IterableApi.handleAppLink(intent.getDataString());
134+
// Overwrite the intent to make sure we don't open the deep link
135+
// again when the user opens our app later from the task manager
136+
setIntent(new Intent(Intent.ACTION_MAIN));
137+
}
138+
}
139+
```
55140

56-
From your application's [onCreate] (https://developer.android.com/reference/android/app/Activity.html#onCreate(android.os.Bundle)) call `getAndTrackDeeplink` along with a callback to handle the destination deeplink url.
141+
Alternatively, call `getAndTrackDeeplink` along with a callback to handle the original deeplink url. You can use this method for any incoming URLs, as it will execute the callback without changing the URL for non-Iterable URLs.
57142

58143
```java
59-
protected void onCreate(Bundle savedInstanceState) {
60-
String dataUri = this.getIntent().getDataString();
61-
IterableHelper.IterableActionHandler clickCallback =
62-
new IterableHelper.IterableActionHandler(){
63-
@Override
64-
public void execute(String result) {
65-
Log.d("HandleDeeplink", "Redirected to: "+ result);
66-
//handle deeplink here
67-
}
68-
};
69-
70-
IterableApi.getAndTrackDeeplink(dataUri, clickCallback);
71-
}
144+
IterableApi.getAndTrackDeeplink(uri, new IterableHelper.IterableActionHandler() {
145+
@Override
146+
public void execute(String result) {
147+
Log.d("HandleDeeplink", "Redirected to: "+ result);
148+
// Handle the original deep link URL here
149+
}
150+
});
72151
```
73152

153+
154+
## Additional Information
155+
156+
See our [setup guide](https://support.iterable.com/hc/en-us/articles/115000331943-Setting-up-Android-Push-Notifications) for more information.
157+
158+
Also see our [push notification setup FAQs](http://support.iterable.com/hc/en-us/articles/206791196-Push-Notification-Setup-FAQ-s).
159+
160+
## Optional Setup
161+
162+
### GCM -> Firebase migration
163+
The recommended migration path is to upgrade the existing Google Cloud project to Firebase, update the server token in the existing GCM push integration in Iterable with the new Firebase token, and update the Android app to support Firebase. If you keep using the same project for FCM and the same integration name, the old tokens will still be valid and won't require re-registration of existing devices.
164+
165+
If you're using a different project for FCM and have existing devices on a GCM project with a different sender ID, updating the app will generate new tokens for users, but the old tokens will still be valid. When migrating from one sender ID to another, specify `legacyGCMSenderId` in `IterableConfig` when initializing the SDK. This will disable old tokens to make sure users won't receive duplicate notifications.
166+
74167
## License
75168

76169
The MIT License

0 commit comments

Comments
 (0)