Webpush destination client library to interact with various IBM Cloud Event Notifications Service.
Disclaimer: this SDK is being released initially as a pre-release version. Changes might occur which impact applications that use this SDK.
The IBM Cloud Event Notifications Service Webpush destination SDK allows developers to register for Chrome and Firefox destiantions of Event Notifications service in IBM cloud.
| Service Name | Artifact Coordinates |
|---|---|
| Event Notifications Service | ENPush:0.2.0 |
- An IBM Cloud account.
- An Event Notifications Instance
- An IAM API key to allow the SDK to access your account. Create one here.
The current version of this SDK is: 0.2.0
Downlaod the latest version from Github
SDK Methods to consume
- Installation
- Initialize SDK
- Register for notifications
- Unregistering from notifications
- Event Notifications destination tags subscriptions
- Notification options
- Notification Status reports
-
Add the
ENPushSDK.js,ENPushServiceWorker.jsandmanifest_Website.jsonfiles to your project root folder. -
Edit the manifest_Website.json file.
{ "name": "YOUR_WEBSITE_NAME" }
-
Change the
manifest_Website.jsonfile name tomanifest.json. -
Include the manifest.json in tag of your html file.
<link rel="manifest" href="manifest.json">
-
Include IBM Cloud Web push SDK to the script ,
<script src="ENPushSDK.js" async></script>
Set the SDK to connect to Event Notification service by using a private endpoint that is accessible only through the IBM Cloud private network.
enPush.UsePrivateEndpoint(true)This must be done before calling the initialize function on the SDK.
Note: Currently private end point is not supported over Safari destination.
Complete the following steps to enable Website to initialize the SDK.
var enPush = new ENPush()
function callback(response) {
alert(response.response)
}
var initParams = {
"instanceGUID": "<instance_guid>",
"apikey": "<instance_apikey>",
"region": "<region>",
"deviceId": "<YOUR_DEVICE_ID>",
"chromeDestinationId": "<chrome_destination_id>",
"chromeApplicationServerKey": "<Chrome_VapId_public_key>",
"firefoxDestinationId": "<firefox_destination_id>",
"firefoxApplicationServerKey": "<Firefox_VapId_public_key>",
"safariDestinationId": "<IBM-Cloud-en-instance-safari-destination-id>",
"websitePushIdSafari": "<safari-web-push-id>"
}
enPush.initialize(initParams, callback)- region : Region of the Event Notifications Instance. eg;
us-south,eu-gb,au-syd,eu-deand 'eu-es' - deviceId: Optional deviceId for device registration.
Use the register() or registerWithUserId() API to register the device with IBM Cloud Event Notifications service. Choose either of the following options:
-
Register without UserId:
enPush.register(function(response) { alert(response.response) })
-
Register with UserId. For
userIdbased notification, the register method will accept one more parameter -userId.enPush.registerWithUserId("UserId",function(response) { alert(response.response) })
UserId is the user identifier value with which you want to register devices in the push service instance.
Use the following code snippets to un-register from Event Notifications.
enPush.unRegisterDevice(function(response) {
alert(response.response)
}Note: To unregister from the
UserIdbased registration, you have to call the registration method. See theRegister without userId optionin Register for notifications.
The subscribe API will subscribe the device for a given tag. After the device is subscribed to a particular tag, the device can receive notifications that are sent for that tag.
Add the following code snippet to your web application to subscribe to a list of tags.
enPush.subscribe(tagName, function(response) {
alert(response.response)
})The getSubscriptions API will return the list of tags to which the device is subscribed. Use the following code snippets in the mobile application to get the subscription list.
enPush.retrieveSubscriptions(function(response){
alert(response.response);
})The unSubscribe API will remove the device subscription from the list tags. Use the following code snippets to allow your devices to get unsubscribe from a tag.
// unsubscibe from the given tag ,that to which the device is subscribed.
enPush.unSubscribe(tagName, function(response) {
alert(response.response)
}To send DeviceId use the setDeviceId method of ENPushNotificationOptions class.
ENPushNotificationOptions options = new ENPushNotificationOptions();
options.setDeviceid("YOUR_DEVICE_ID");Note: Remember to keep custom DeviceId
uniquefor each device.
To enable/disable the message status report, use the following method,
enPush.enableMessageStatusReport(true) // send false for disabling the status.Note: By default status reporting is disabled. Status tracking feature is not supported for safari browser and it is available for Firefox and Chrome browsers.
If you are having difficulties using this SDK or have a question about the IBM Cloud services, please ask a question at Stack Overflow.
If you encounter an issue with the project, you are welcome to submit a bug report. Before that, please search for similar issues. It's possible that someone has already reported the problem.
Find more open source projects on the IBM Github Page
See CONTRIBUTING.
The IBM Cloud Event Notifications Service Webpush destination SDK is released under the Apache 2.0 license. The license's full text can be found in LICENSE.