This service endpoints aim at providing a way to handle notifications from and to users and apps:

Any application or user can create and manage several notifications. The service provide two different way to receive notification,by push o by pull .

The push way requires the registration of the application and user, at the Communicator Service . In the registration phase, the developer must specify the parameters that need to be saved in Communicator Service, the parameters are used by the push service, such as Google Cloud message.
There are two types of parameters, public and private.
Public ones are shared with the client side.
Private ones, only aware only the server side.

The Communicator service exposes some method to get the public parameters of a specific app,this is usefull for some push service of third party where the client must know the server configuration.

The following data structures define the objects:

* Notification:

• id (String) identify the notification
• updateTime (long) is the time when notification was modified
• version (long) is the number of modified from the orginal version
• title (String) is the title of notification
• description (String) is the description of the notification
• type (String) is the source of notification
• user (String) id of the user “owning” the notification
• content (Map<String, Object>) content of the notification
• timestamp (long) is the time when notification was created
• starred (boolean) starred flag
• labelIds (List<String> ) label ids
• channelIds (List<String>) channel ids
• entities (List<EntityObject>) list of entities
• author (NotificationAuthor) notification author
• readed (boolean) readed flag

* NotificationAuthor:

• appId (String) Appid from permission provider portal
• userId (String) userid from smartcampus

* AppSignature:

• appId (String) Appid from permission provider portal
• publicKey (Map<String,Object>) set the user visible key/value list for Push Notification
• privateKey (Map<String,Object>) set the hidden key/value list for Push Notification

* UserSignature:

• appName (String) Appid from permission provider portal
• registrationId (String) from Android registration

—–

To get a notification we have different levels of filtering, we have the notifications user 's related to the app you are using, the user notifications related to a specific app notifications and general user.
The methods to receive notitifche need the Oauth token of the user and the appid, specifically the name of the ap log onto the portal smartcampus.

A notification can 'be sought in the list or id, can' be modified and deleted with their methods and permits required on the portal smartcampus

First thing to do to register an app to push service and 'regsitrare the app at a push service third party (apple / google). After receiving the connection parameters, you regsitra, if you do not have it already 'done, the app on the portal smartcampus asking permission to the Communciator Service.

Received permission, you pass the portal registration of Communicator app on Service. Here stating the required parameters, such as public and private keys to be saved in the configuration of Communicator Service, you save the regsitrazione.

After that, you can 'take from the client (mobile / web) public keys in order to receive push notifications. The client / user must 'register itself in turn on the Communicator Service, specifying what kind of app to receive notifications.

The request is emitted to the following endpoint:

https://dev.smartcommunitylab.it/core.communicator

The method allows for accessing the notifications of the current user.

Permission

communicator.user.msg.read

Request

GET core.communicator/user/notification HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

Response

{
notifications: [1]
	0:  {
		id: "51fb7ef744aeb91b6a6a2f16"
		updateTime: -1
		version: 623
		user: "1"
		title: "Test notification"
		description: null
		type: "user"
		content: null
		timestamp: 0
		starred: false
		labelIds: [0]
		channelIds: [0]
		entities: [0]
		author: {
				appId: null
				userId: "1"
			}
		readed: false
	}
}

The method allows for accessing the notification of the specified user. The notification ID is passed as the path element.

Permission

communicator.user.msg.read

Request

GET /core.communicator/user/notification/{Id} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer { user access token}

Response

{
	id: "51fb7ef744aeb91b6a6a2f16"
	updateTime: -1
	version: 623
	user: "1"
	title: "Test notification"
	description: null
	type: "user"
	content: null
	timestamp: 0
	starred: false
	labelIds: [0]
	channelIds: [0]
	entities: [0]
	author: {
		appId: null
		userId: "1"
	}
	readed: false
}

The method allows for updating the notification of the specified user. The notification ID is passed as the path element.

Permission

communicator.user.msg.write

Parameters:

• Request body representing key→ value pairs (with complex keys) to be matched against the Notification content (JSON object).

Request

PUT /core.communicator/user/notification/{Id} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer { user access token}

Body:

{
	id: "51fb7ef744aeb91b6a6a2f16"
	updateTime: -1
	version: 623
	user: "1"
	title: "Test notification"
	description: null
	type: "user"
	content: null
	timestamp: 0
	starred: false
	labelIds: [0]
	channelIds: [0]
	entities: [0]
	author: {
		appId: null
		userId: "1"
	}
	readed: false
}

Response: empty

The method allows for deleting the notification of the specified user. The notification ID is passed as the path element.

Permission

communicator.user.msg.write

Request

DELETE /core.communicator/user/notification/{Id} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer { user access token}

Response: empty

The method allows for accessing the notifications of the current user.The app ID, app_id, is passed as the path element

Permission

communicator.app.msg.read.{app_id}

Parameters:

• app_id App Id. Should be equivalent to one of the profile type resource parameters defined in the developer console.

Request

GET core.communicator/app/{app_id}/notification HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

Response

{
notifications: [1]
	0:  {
		id: "51fb7ef744aeb91b6a6a2f16"
		updateTime: -1
		version: 623
		user: "1"
		title: "Test notification"
		description: null
		type: "user"
		content: null
		timestamp: 0
		starred: false
		labelIds: [0]
		channelIds: [0]
		entities: [0]
		author: {
				appId: null
				userId: "1"
			}
		readed: false
	}
}

The method allows for accessing the notification of the specified user. The notification ID is passed as the path element.The app ID, app_id, is passed as the path element

Permission

communicator.app.msg.read.{app_id}

Parameters:

• app_id App Id. Should be equivalent to one of the profile type resource parameters defined in the developer console.

Request

GET /core.communicator/app/{app_id}/notification/{Id} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer { user access token}

Response

{
	id: "51fb7ef744aeb91b6a6a2f16"
	updateTime: -1
	version: 623
	user: "1"
	title: "Test notification"
	description: null
	type: "user"
	content: null
	timestamp: 0
	starred: false
	labelIds: [0]
	channelIds: [0]
	entities: [0]
	author: {
		appId: null
		userId: "1"
	}
	readed: false
}

The method allows for updating the notification of the specified user. The notification ID is passed as the path element.The app ID, app_id, is passed as the path element

Permission

communicator.app.msg.write.{app_id}

Parameters:

• app_id App Id. Should be equivalent to one of the profile type resource parameters defined in the developer console.
• Request body representing key→ value pairs (with complex keys) to be matched against the Notification content (JSON object).

Request

PUT /core.communicator/app/{app_id}/notification/{Id} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer { user access token}

Body:

{
	id: "51fb7ef744aeb91b6a6a2f16"
	updateTime: -1
	version: 623
	user: "1"
	title: "Test notification"
	description: null
	type: "user"
	content: null
	timestamp: 0
	starred: false
	labelIds: [0]
	channelIds: [0]
	entities: [0]
	author: {
		appId: null
		userId: "1"
	}
	readed: false
}

Response: empty

The method allows for deleting the notification of the specified user. The notification ID is passed as the path element.The app ID, app_id, is passed as the path element

Permission

communicator.app.msg.write.{app_id}

Parameters:

• app_id (path element). App id

Request

DELETE /core.communicator/app/{app_id}/notification/{Id} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer { user access token}

Response: empty

The method allows receiving the configuration of the user in communicator service.

Permission

communicator.register.user.{app_id}

Request

GET /core.communicator/configuration/user/{app_id} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer { user access token}

Response: Map<String,String> with key/value settings for Push Service

The method allows reading the public configuration of the app in communicator service. The return map are the public parameters setted in the registration step of the app.

Permission

communicator.register.user.{app_id}

Request

GET /core.communicator/configuration/public/{app_id} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer { user access token}

Response: Map<String,String> with key/value settings for Push Service

The method permit the user to receive the push notifications.After calling ,in android app, le GCM library to receive the RegistrationId, the user must send it to the Communicator Service

Permission

communicator.register.user.{app_id}

Parameters:

• Request body representing key→ value pairs (with complex keys) to be matched against the Notification content (JSON object).

Request

POST /core.communicator/register/user/{app_id} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer { user access token}

Body:

{

	“appName”:”app_id”,

	“registrationId”:”<from android gcm lib>”
}

Response: empty

The method allows the cancellation of the registration to the Communicator Service,the user must specify the app setted at the registration

Permission

communicator.register.user.{app_id}

Request

DELETE /core.communicator/unregister/user/{app_id} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer { user access token}

Response: empty

The method allows sending the app notifications .The author of the notification is the app and the notification can be sended to a list of users. There is a web page where is possible to send a notification with your app in Communicator Service Web page for send notification

The users are identified by id in smartcampus platform

Permission

communicator.send.app.{app_id}

Parameters:

• Request body representing key→ value pairs (with complex keys) to be matched against the Notification content (JSON object).

Request

POST /core.communicator/send/app/{app_id}?users={users id...} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client  access token}

Body:

{
	id: "51fb7ef744aeb91b6a6a2f16"
	updateTime: -1
	version: 623
	user: "1"
	title: "Test notification"
	description: null
	type: "user"
	content: null
	timestamp: 0
	starred: false
	labelIds: [0]
	channelIds: [0]
	entities: [0]
	author: {
		appId: null
		userId: "1"
	}
	readed: false
}

Response: empty

The method allows registering the app at Communicator Service,the registration allows to save parameters for sending push notifications. The parameters is divide in public and private,depends if the client can read or not the value.There is a web page where is possible to register your app in Communicator Service Web page for registration

Permission

communicator.register.app.{app_id}

Parameters:

• Request body representing key→ value pairs (with complex keys) to be matched against the Notification content (JSON object).

Request

POST /core.communicator/register/app/{app_id} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client  access token}

Body:

{

     "appId":"<App name>",
     "publicKey":{
                  "GCM_SENDER_ID":”<from gcm registration page Google>”
                  },
     "privateKey":{
                  "GCM_SENDER_API_KEY":”<from gcm registration page Google>”
                  }
}

Response: empty

The method allows the cancellation of the app account to the Communicator Service.

Permission

communicator.register.{app_id}

Request

DELETE /core.communicator/unregister/app/{app_id} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client  access token}

Response: empty

The method allows reading the configuration of the app saved communicator service. The returned key/value list was setted at registration step

Permission

communicator.register.{app_id}

Request

GET /core.communicator/configuration/app/{app_id} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer { client access token}

Response: AppSignature json object with key/value settings for Push Service

The Communicator Service client library provides an access to the operations exposed by the Communciator Service REST APIs.

The source code of the library is available at https://github.com/smartcampuslab/communicator.client.

To use the library, one has to include the communicator.client-2.0.jar and the smartcampus-client-commons-2.0.jar into the project classpath. Also, the Jackson library for JSON parsing is required. In case of Android application, the library should be placed into the libs folder. When Maven is used to manage project libraries, one can use the following dependency:

	<dependency>
		<groupId>eu.trentorise.smartcampus</groupId>
		<artifactId>communicator.client</artifactId>
		<version>2.x</version>
		<scope>jar</scope>
	</dependency>

Note that the SmartCommunity repository should be included in Maven configuration, e.g.:

	<repository>
		<id>SmartCommunity</id>
		<url>http://repository.smartcampuslab.it/content/groups/public</url>
	</repository>

The functionality is exposed classes, namely CommunicatorConnector. The following code demonstrates how the class may be used:

CommunicatorConnector communicatorConnector=new CommunicatorConnector("https://dev.smartcommunitylab.it/core.communicator",<appid>);
 
 
//reuqest server public parameters for push service	
Map<String, Object> x = communicatorConnector.requestPublicConfigurationToPush(<APPID>,<USER_AUTH_TOKEN>);
 
 
//Set user configuration parameter
UserSignature signature = new UserSignature();
signature.setRegistrationId("<Received from Android GCM lib>");
signature.setAppName(<appid>);
 
//register user
communicatorConnector.registerUserToPush(<APPID>,signature, <USER_AUTH_TOKEN>);
 
 
 
 
//create list of user tos end notification
List<String> users = new ArrayList<String>();
users.add("39");
users.add("40");
 
//create notiifcation
Notification not = new Notification();
not.setDescription("Check in update e delete");
not.setTitle("Check in update e delete");
not.setType(<APPID>);
not.setUser("1");
not.setId(null);
NotificationAuthor author = new NotificationAuthor();
author.setUserId(<USERID>);
not.setAuthor(author);
 
 
//send notification
	communicatorConnector.sendAppNotification(notification, <APPID>,
				users, <CLIENT_AUTH_TOKEN>);
 
//get all notification
Notifications results = communicatorConnector
				.getNotificationsByUser(0L, 0, -1, <USER_AUTH_TOKEN>);
 
Notification notification = results.getNotifications().get(0);
 
 
//get notification by Id
notification = communicatorConnector.getNotificationByUser(
				notification.getId(), <USER_AUTH_TOKEN>);
 
 
 
//modify notification		
notification.setStarred(true);
communicatorConnector.updateByUser(notification, notification.getId(),<USER_AUTH_TOKEN>);
 
 
 
//delete notification
communicatorConnector.deleteByUser(notification.getId(), <USER_AUTH_TOKEN>);
 
//unregister user to push service
communicatorConnector.unregisterUserToPush(<APPID>, <USER_AUTH_TOKEN>);

The Push Service client library provides an access to the operations exposed by the Communciator Service REST APIs about push services.

To use the library,in Android application, the library push.service.jar should be placed into the libs folder.

The functionality is exposed classes, namely PushServiceConnector. The following code demonstrates how the class may be used:

//create connector in the beginning of application flow 
PushServiceConnector connector=new PushServiceConnector();
 
//init connector
connector.init({android context});

In AndroidManifest.xml must be setted

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.GET_ACCOUNTS" />
    <uses-permission android:name="android.permission.WAKE_LOCK" />
    <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
 
    <permission
        android:name="eu.trentorise.smartcampus.pushservice.permission.C2D_MESSAGE"
        android:protectionLevel="signature" />
 
    <uses-permission android:name="eu.trentorise.smartcampus.pushservice.permission.C2D_MESSAGE" />
 
            <meta-data
                android:name="SERVER_URL"
                android:value="https://dev.smartcommunitylab.it/core.communicator" />
            <meta-data
                android:name="APP_ID"
                android:value="{nome dell app registrato sul portale smartcampus}" />
            <meta-data
                android:name="USER_AUTH_TOKEN"
                android:value="{token sul portale smartcampus}" />
 
 
	<application >
 
        <activity> ... </activity>
 
        <receiver
            android:name=".NotificationReceiver"
            android:permission="com.google.android.c2dm.permission.SEND" >
            <intent-filter>
                <action android:name="com.google.android.c2dm.intent.RECEIVE" />
 
                <category android:name="eu.trentorise.smartcampus.pushservice" />
            </intent-filter>
        </receiver>
 
        <service android:name=".NotificationService" />
 
    </application>

~~DISQUS~~