Skip to content

Update Android push docs, and app setup for 1.17.0 #522

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Jawnnypoo wants to merge 2 commits into from
Closed

Update Android push docs, and app setup for 1.17.0 #522

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9ccd466
Update Android push docs, and app setup for 1.17.0
Jawnnypoo May 2, 2018
0b2a2d3
Remove unused doc
Jawnnypoo May 2, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 4 additions & 51 deletions _includes/android/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,45 +9,12 @@ Add dependency to the application level `build.gradle` file.

```groovy
dependencies {
implementation 'com.parse:parse-android:1.16.7'
implementation 'com.parse:parse-android:latest.version.here'
Copy link
Contributor

@rogerhu rogerhu May 4, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we should put a comment about adding the FCM package here as optional

implementation 'com.parse:parse-fcm-android:latest.version.here'

Copy link
Member Author

@Jawnnypoo Jawnnypoo May 4, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think maybe we should have a note about push somewhere in the README, but there are plenty of people/apps that use Parse Android without using any form of push, so I think it might be confusing here.

}
```

**Step 2:** Setup Parse

- **Option 1:** Setup in the Manifest

You may define `com.parse.SERVER_URL` and `com.parse.APPLICATION_ID` meta-data in your `AndroidManifest.xml`:

```xml
<application ...>
<meta-data
android:name="com.parse.SERVER_URL"
android:value="@string/parse_server_url" />
<meta-data
android:name="com.parse.APPLICATION_ID"
android:value="@string/parse_app_id" />
...
</application>
```

Initializing Parse in the `Application`

```java
import com.parse.Parse;
import android.app.Application;

public class App extends Application {
@Override
public void onCreate() {
super.onCreate();
Parse.initialize(this);
}
}
```

- **Option 2:** Setup in the `Application`

Initialize Parse using your server configuration:
```java
import com.parse.Parse;
import android.app.Application;
Expand All @@ -58,33 +25,19 @@ public class App extends Application {
super.onCreate();
Parse.initialize(new Parse.Configuration.Builder(this)
.applicationId("YOUR_APP_ID")
.clientKey("YOUR_CLIENT_KEY")
Copy link
Contributor

@rogerhu rogerhu May 2, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Client key can be null, as it is by default

.server("http://localhost:1337/parse/")
.build()
);
}
Copy link
Contributor

@rogerhu rogerhu May 2, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't we have to do ParseFCM.register(this); in the Application instance if we want push?

(Or ParseGCM.register(this)) for an older version..)

Copy link
Member Author

@Jawnnypoo Jawnnypoo May 2, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nope, it is not required for FCM. I think we will leave the GCM instructions out of here, only mentioning it at the bottom, so that people will move away from it.

Copy link
Contributor

@rogerhu rogerhu May 2, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was playing with it last night but couldnt get stuff to fire unless I did the register command with FCM...you sure it works without it?

Copy link
Contributor

@rogerhu rogerhu May 4, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Never mind, I was putting a breakpoint on the wrong place. Works fine!

Copy link
Contributor

@rogerhu rogerhu May 4, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See my updates about how a JobService is scheduled to run when the app starts:

https://github.com/parse-community/Parse-SDK-Android/pull/817/files
image

}
```

For either option, the custom `Application` class must be registered in `AndroidManifest.xml`:
The custom `Application` class must be registered in `AndroidManifest.xml`:
```xml
<application
android:name=".App"
...>
...
</application>
```

**Step 3:** Setup permissions in the Manifest

You have to define `INTERNET`permissions in your `AndroidManifest.xml`:

```xml
<manifest ...>

<uses-permission android:name="android.permission.INTERNET" />

<application ...>
...
</application>
</manifest>
```
37 changes: 6 additions & 31 deletions _includes/android/push-notifications.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,29 +8,7 @@ If you haven't installed the SDK yet, [head over to the Push QuickStart]({{ site

If you want to start using push, start by completing the [Android Push Notifications QuickStart Guide]({{ site.baseUrl }}/parse-server/guide/#push-notifications-quick-start) to learn how to configure your app and send your first push notification. Come back to this guide afterwards to learn more about the push features offered by Parse.

The Parse library provides push notifications using Google Cloud Messaging (GCM) if Google Play Services are available. Learn more about Google Play Services [here](https://developers.google.com/android/guides/overview).

When sending pushes to Android devices with GCM, there are several pieces of information that Parse keeps track of automatically:

* **Registration ID**: The GCM registration ID uniquely identifies an app/device pairing for push purposes.
* **Sender ID**: The GCM sender ID is a public number that identifies the sender of a push notification.
* **API key**: The GCM API key is a server secret that allows a server to send pushes to a registration ID on behalf of a particular sender ID.

The Parse Android SDK now requires you to specify the GCM sender ID with the following `<meta-data>` tag as a child of the `<application>` element in your app's `AndroidManifest.xml`:

```java
<meta-data android:name="com.parse.push.gcm_sender_id"
android:value="id:YOUR_SENDER_ID" />;
```

In the sample snippet above, `YOUR_SENDER_ID` should be replaced by a numeric GCM sender ID. Note that the Parse SDK expects you to prefix your sender ID with an `id:` prefix, as shown in the sample snippet.

If you want to register your app with multiple additional sender IDs, then the `android:value` in the `<meta-data>` element above should hold a comma-delimited list of sender IDs, as in the following snippet:

```java
<meta-data android:name="com.parse.push.gcm_sender_id"
android:value="id:YOUR_SENDER_ID_1,YOUR_SENDER_ID_2,YOUR_SENDER_ID_3" />;
```
The Parse library provides push notifications using Firebase Cloud Messaging (FCM) if Google Play Services are available. Learn more about Google Play Services [here](https://firebase.google.com/docs/cloud-messaging/).
Copy link
Contributor

@rogerhu rogerhu May 2, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this section should include the fact that calling ParseFCM.register(this) automatically passes the Installation object to the Parse server as a GCM token type.

Copy link
Member Author

@Jawnnypoo Jawnnypoo May 2, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The user should never have to call this manually given our setup. Do you think we should still mention that it is happening?


## Installations

Expand All @@ -48,9 +26,8 @@ While it is possible to modify a `ParseInstallation` just like you would a `Pars
* **`channels`**: An array of the channels to which a device is currently subscribed.
* **`installationId`**: Unique Id for the device used by Parse _(readonly)_.
* **`deviceType`**: The type of device, "ios", "osx", "android", "winrt", "winphone", "dotnet", or "embedded". On Android devices, this field will be set to "android" _(readonly)_.
* **`pushType`**: This field is reserved for directing Parse to the push delivery network to be used. If the device is registered to receive pushes via GCM, this field will be marked "gcm". If Google Play Services is not available, it will be blank _(readonly)_.
* **`GCMSenderId`**: This field only has meaning for Android `ParseInstallation`s that use the GCM push type. It is reserved for directing Parse to send pushes to this installation with an alternate GCM sender ID. This field should generally not be set unless you are uploading installation data from another push provider. If you set this field, then you must set the GCM API key corresponding to this GCM sender ID in your Parse application's push settings.
* **`deviceToken`**: The token used by GCM to keep track of registration ID. On iOS devices, this is the Apple generated token _(readonly)_.
* **`pushType`**: This field is reserved for directing Parse to the push delivery network to be used. If the device is registered to receive pushes via FCM, this field will be marked "gcm". If Google Play Services is not available, it will be blank _(readonly)_.
* **`deviceToken`**: The token used by FCM to keep track of registration ID. On iOS devices, this is a generated token _(readonly)_.
* **`appName`**: The display name of the client application to which this installation belongs. This value is synchronized every time a `ParseInstallation` object is saved from the device _(readonly)_.
* **`appVersion`**: The version string of the client application to which this installation belongs. This value is synchronized every time a `ParseInstallation` object is saved from the device _(readonly)_.
* **`parseVersion`**: The version of the Parse SDK which this installation uses. This value is synchronized every time a `ParseInstallation` object is saved from the device _(readonly)_.
Expand Down Expand Up @@ -341,7 +318,7 @@ Make sure you've gone through the [Android Push QuickStart]({{ site.baseUrl }}/p

When a push notification is received, the “title” is displayed in the status bar and the “alert” is displayed alongside the “title” when the user expands the notification drawer. If you choose to subclass `com.parse.ParsePushBroadcastReceiver`, be sure to replace that name with your class' name in the registration.

Note that some Android emulators (the ones without Google API support) don't support GCM, so if you test your app in an emulator make sure to select an emulator image that has Google APIs installed.
Note that some Android emulators (the ones without Google API support) don't support FCM, so if you test your app in an emulator make sure to select an emulator image that has Google APIs installed.

### Customizing Notifications

Expand Down Expand Up @@ -520,11 +497,9 @@ You can check the Push Delivery Report for the cause of failed deliveries: Misma

If everything looks great so far, but push notifications are not showing up on your phone, there are a few more things you can check.

* [Upgrade to the latest SDK](https://github.com/parse-community/Parse-SDK-Android). This documentation covers the push API introduced in the 1.7.0 version of the Android Parse SDK. Please upgrade if you are getting compiler errors following these instructions.
* Make sure you are using the correct `packageName` in your `AndroidManifest.xml`.
* Make sure you have the correct permissions listed in your `AndroidManifest.xml` file, as outlined in the [Android Push Quickstart]({{ site.baseUrl }}/parse-server/guide/#push-notifications-quick-start). If you are using a a custom receiver, be sure you have registered it in the Manifest file with the correct `android:name` property and the proper intent filters.
* [Upgrade to the latest SDK](https://github.com/parse-community/Parse-SDK-Android). This documentation covers the push API introduced in the 1.17.0 version of the Android Parse SDK. Please upgrade if you are getting compiler errors following these instructions.
* Make sure you've used the correct App ID and client key, and that `Parse.initialize()` is being called. `Parse.initialize()` lets the service know which application it is listening for; this code must be in your `Application.onCreate` rather than `Activity.onCreate` for a particular `Activity`, so that any activation technique will know how to use Parse.
* Check that the push registration call is being called successfully. Your device must successfully register a ParseInstallation object with a valid GCM Registration id in the "deviceToken" field, if using GCM.
* Check that the push registration call is being called successfully. Your device must successfully register a ParseInstallation object with a valid FCM Registration id in the "deviceToken" field
* Check that the device is set to accept push notifications from your app.
* Note that, by design, force-killed apps will not be able to receive push notifications. Launch the app again to reenable push notifications.
* Check the number of subscribers in your Parse Push Console. Does it match the expected number of subscribers? Your push might be targeted incorrectly.
Expand Down
2 changes: 1 addition & 1 deletion _includes/dotnet/push-notifications.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ While it is possible to modify a `ParseInstallation` just like you would a `Pars
* **`timeZone`**: The current time zone where the target device is located. This field is readonly and can be accessed via the `TimeZone` property. This value is synchronized every time an `Installation` object is saved from the device.
* **`localeIdentifier`**: The locale identifier of the device in the format [language code]-[COUNTRY CODE]. The language codes are two-letter lowercase ISO language codes (such as "en") as defined by [ISO 639-1](http://en.wikipedia.org/wiki/ISO_639-1). The country codes are two-letter uppercase ISO country codes (such as "US") as defined by [ISO 3166-1](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-3). This value is synchronized every time a `ParseInstallation` object is saved from the device _(readonly)_.
* **`deviceType`**: The type of device, "ios", "android", "winrt", "winphone", or "dotnet". This field is readonly and can be accessed via the `DeviceType` property.
* **`pushType`**: This field is reserved for directing Parse to the push delivery network to be used. If the device is registered to receive pushes via GCM, this field will be marked "gcm". If this device is not using GCM, and is using Parse's push notification service, it will be blank _(readonly)_.
* **`pushType`**: This field is reserved for directing Parse to the push delivery network to be used. If the device is registered to receive pushes via FCM, this field will be marked "gcm". If this device is not using FCM, it will be blank _(readonly)_.
* **`installationId`**: Unique Id for the device used by Parse. This field is readonly and can be accessed via the `InstallationId` property.
* **`deviceToken`**: The Apple generated token used for iOS devices, or Google generated token used for Android devices _(readonly)_.
* **`channelUris`**: The Microsoft-generated push URIs for Windows devices. This field is readonly and can be accessed via the `DeviceUris` property.
Expand Down
3 changes: 1 addition & 2 deletions _includes/ios/push-notifications.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,15 +55,14 @@ While it is possible to modify a `PFInstallation` just like you would a `PFObjec
* **`badge`**: The current value of the icon badge for iOS/OS X apps. Changing this value on the `PFInstallation` will update the badge value on the app icon. Changes should be saved to the server so that they will be used for future badge-increment push notifications.
* **`installationId`**: Unique Id for the device used by Parse _(readonly)_.
* **`deviceType`**: The type of device, "ios", "osx", "android", "winrt", "winphone", "dotnet", or "embedded". On iOS and OS X devices, this field will be set to "ios" and "osx", respectively _(readonly)_.
* **`deviceToken`**: The Apple generated token used for iOS/OS X devices. On Android devices, this is the token used by GCM to keep track of registration ID _(readonly)_.
* **`deviceToken`**: The Apple generated token used for iOS/OS X devices. On Android devices, this is the token used by FCM to keep track of registration ID _(readonly)_.
* **`appName`**: The display name of the client application to which this installation belongs. In iOS/OS X, this value is obtained from `kCFBundleNameKey`. This value is synchronized every time a `PFInstallation` object is saved from the device _(readonly)_.
* **`appVersion`**: The version string of the client application to which this installation belongs. In iOS/OS X, this value is obtained from `kCFBundleVersionKey`. This value is synchronized every time a `PFInstallation` object is saved from the device _(readonly)_.
* **`appIdentifier`**: A unique identifier for this installation's client application. In iOS/OS X, this value is obtained from `kCFBundleIdentifierKey`. This value is synchronized every time a `PFInstallation` object is saved from the device _(readonly)_.
* **`parseVersion`**: The version of the Parse SDK which this installation uses. This value is synchronized every time a `PFInstallation` object is saved from the device _(readonly)_.
* **`timeZone`**: The current time zone where the target device is located. This value is synchronized every time a `PFInstallation` object is saved from the device _(readonly)_.
* **`localeIdentifier`**: The locale identifier of the device in the format [language code]-[COUNTRY CODE]. The language codes are two-letter lowercase ISO language codes (such as "en") as defined by [ISO 639-1](http://en.wikipedia.org/wiki/ISO_639-1). The country codes are two-letter uppercase ISO country codes (such as "US") as defined by [ISO 3166-1](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-3). This value is synchronized every time a `PFInstallation` object is saved from the device _(readonly)_.
* **`pushType`**: This field is reserved for directing Parse to the push delivery network to be used for Android devices. This parameter is not supported in iOS/OS X devices _(readonly)_.
* **`GCMSenderId`**: This field only has meaning for Android `PFInstallation`s that use the GCM push type. This parameter is not supported in iOS/OS X devices.
* **`channelUris`**: The Microsoft-generated push URIs for Windows devices _(readonly)_.

The Parse SDK will avoid making unnecessary requests. If a `PFInstallation` is saved on the device, a request to the Parse servers will only be made if one of the `PFInstallation`'s fields has been explicitly updated.
Expand Down
4 changes: 2 additions & 2 deletions _includes/js/push-notifications.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,9 +26,9 @@ This class has several special fields that help you manage and target devices.
* **`channels`**: An array of the channels to which a device is currently subscribed.
* **`timeZone`**: The current time zone where the target device is located. This value is synchronized every time an `Installation` object is saved from the device.
* **`deviceType`**: The type of device, "ios", "android", "winrt", "winphone", or "dotnet"_(readonly)_.
* **`pushType`**: This field is reserved for directing Parse to the push delivery network to be used. If the device is registered to receive pushes via GCM, this field will be marked "gcm". If this device is not using GCM, and is using Parse's push notification service, it will be blank _(readonly)_.
* **`pushType`**: This field is reserved for directing Parse to the push delivery network to be used. If the device is registered to receive pushes via FCM, this field will be marked "gcm". If this device is not using FCM, and is using Parse's push notification service, it will be blank _(readonly)_.
* **`installationId`**: Universally Unique Identifier (UUID) for the device used by Parse. It must be unique across all of an app's installations. _(readonly)_.
* **`deviceToken`**: The Apple or Google generated token used to deliver messages to the APNs or GCM push networks respectively.
* **`deviceToken`**: The Apple or Google generated token used to deliver messages to the APNs or FCM push networks respectively.
* **`channelUris`**: The Microsoft-generated push URIs for Windows devices.
* **`appName`**: The display name of the client application to which this installation belongs.
* **`appVersion`**: The version string of the client application to which this installation belongs.
Expand Down
8 changes: 0 additions & 8 deletions _includes/parse-server/compatibility.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -159,14 +159,6 @@ Push notification support for the Parse IoT SDKs is provided through the Parse P

Hosted Parse applications could disable a security setting in order to allow clients to send push notifications. Parse Server does not allow clients to send push notifications as the `masterKey` must be used. Use Cloud Code or the REST API to send push notifications.

### Android: Exporting GCM Registration IDs

Parse supports sending pushes to Android devices via Google Cloud Messaging (GCM). By default, the GCM registration IDs (stored in the `deviceToken` field) for your app are associated with Parse's GCM sender ID, which won't work after Parse is retired. You may want to take these actions to have your app register with a different GCM sender ID, which will make the registration IDs in the `deviceToken` field exportable to other push providers:

* Enable GCM for your Android project in the [Google Developer Console](https://console.developers.google.com). Take note of your project number (it should be a large integer like `123427208255`). This is also known as your GCM sender ID.
* Add the `com.parse.push.gcm_sender_id` metadata attribute to your app manifest so that Parse registers for push with your GCM sender ID. For instance, if your GCM sender ID is `123427208255`, then you should add a metadata attribute named `com.parse.push.gcm_sender_id` with the value `id:123427208255` (note that the "id:" prefix is required). This attribute requires Android SDK 1.8.0 or higher. See our [Android push guide]({{ site.baseUrl }}/android/guide/#setting-up-push) for more details on this attribute.
* Parse will now register for GCM with both its GCM sender ID and your GCM sender ID on app startup. You can use the resulting GCM registration IDs (stored in the `deviceToken` field of ParseInstallation) with other GCM push providers.

## Schema

Schema validation is built in. Retrieving the schema via API is available.
Expand Down
Loading