◾Custom push gateways

Smartico is integrated with Google Firebase to deliver push notifications for Android and iOS setups. Firebase is a free service and doesn't 'require additional contract signing or complex configurations.

However, there may be instances where push notifications need to be delivered through different services or gateways. For these specific scenarios, Smartico offers two alternative integration methods:

"smartico-by-token" - In such a scenario, Smartico's front-end still collects push tokens from the browsers and native applications and handles their life-cycle (associating token with the user, invalidating in case of token expiration)
"smartico-by-user" - in such a scenario, the Operator should take care about managing push tokens. Smartico will address push notifications using "user id"

To enable these configurations, the push gateway has to be configured in the following way in Smartico BackOffice.

{
    // type of the integration - "smartico-by-token" or "smartico-by-user"
    "gateway-type": "smartico-by-token",
    // URL of the custom gateway that will be called by smartico to deliver the push token
    "URL": "https:/some.com/post_handler", 
    // auth key that will be sent in the HTTP-header: 'Authorization'
    "auth_key": "some_secret_key"
}

The provided URL should expect the following POST message.

{
  // ID of the user in the smartico system
  "user_id": 123123123,
  // ID of the user on operator side
  "user_ext_id": "1123123",
  // ID of the brand, relevant for the multi-brand setups
  "ext_brand_id": "mybrand1",
  // push token for the type of integration "smartico-by-token"
  "push_token": "e311mfDpNx4:APA91bFzTRPjTNMHGBIyrqF46zHQmOk0l77GHHDNlX7MX-PbxDlixbyZWBEDkFlN817RdvQM4AG5Ncspg8Tvy2ab1mj3IbFqERepXWBcCqRVp6y1GwjR7vCFSY6SKNXRNtmpd0rKDGe4",
  // type of device to which this token is assigned
  "device_type": "WINDOWS",
  // message content of the push notification
  "message": {
    // smartico internal message id, should be used also to report impressions/clicks
    "message_id": 123456,
    "body": "some body",
    "title": "short title",
    "action": "https://mysite.com/link.html",
    "iconUrl": "icon",
    "badgeUrl": "badge",
    "imageUrl": "image",
    // ID of the user on operators side prefixed with a unique brand ID, needed for reporting
    "user_ext_id": "684:f21aaf49-54cf-4ff4-b3ce-146bd2535004",
    // Unique ID of the notification
    "engagement_uid": "f56883c4-2898-4388-a033-6205bbc41d8d",
    // URL to the site of the domain for this user, used for Deep links
    // you need to replace {action} parameter with the action that user is clicked and 
    // navigate user with the final link
    // you can also skip this part, if your action is always a final URL
    "_WEB_SITE_DP_HANDLER": "https://demo.smartico.ai/demo.html#_smartico_dp={action}",
  }
}

Service should respond with HTTP status code 200 and body in JSON format:

{
  "error_code": 0
}

In case of an error, report HTTP code 500 and the error message and code (the messages and codes are according to the operator's gateway logic). Example:

{
  "error_code": 1,
  "error_message": "User was not found"
}

Reporting push message status back to Smartico

The gateway can report the fail, delivery, impression (when the push was shown to the end-user) and click on the notification to the Smartico system.

This should be done with a simple HTTP-GET request to one of the following end-points (depending on which environment your label is set):

The format of the request should be

https://papi.smartico.ai/services/public?api_key={label_key}&brand_key={brand_key}&version=1.2.25&event={event_body}

The version may represent the version of the application and be used only for debugging purposes.
label_key - is your label public key, the same as used in the front-end integration on the site
brand_key - is your brand public key, the same as used in the front-end integration on the site

Reporting fail

The event_body for impression should be built in the following way:

{
	// unique uuid for each event
	"uuid": "d404d654-2ef9-44b3-a6e4-4b8934392239", 
	// timestamp of the event with milliseconds
	"ts": 1712570445333,
	"event_type": "engagement_failed",
	// user ext id prefixed with brand id
	"user_ext_id": "684:f21aaf49-54cf-4ff4-b3ce-146bd2535004", 
	"payload": {
		// Unique ID of the notification
		"engagement_uid": "f56883c4-2898-4388-a033-6205bbc41d8d",
		// smartico internal message_id 
		"message_id": 123456,
		// description of error
		"error_message": "error description",
		// fixed constant for the 'Push' type of the communication
		"activity_type": 40
	}
}

Reporting delivery

The event_body for impression should be built in the following way:

{
	// unique uuid for each event
	"uuid": "d404d654-2ef9-44b3-a6e4-4b8934392239", 
	// timestamp of the event with milliseconds
	"ts": 1712570445333,
	"event_type": "engagement_delivered",
	// user ext id prefixed with brand id
	"user_ext_id": "684:f21aaf49-54cf-4ff4-b3ce-146bd2535004", 
	"payload": {
		// Unique ID of the notification
		"engagement_uid": "f56883c4-2898-4388-a033-6205bbc41d8d",
		// smartico internal message_id 
		"message_id": 123456,
		// fixed constant for the 'Push' type of the communication
		"activity_type": 40
	}
}

Reporting Impression

The event_body for impression should be built in the following way:

{
	// unique uuid for each event
	"uuid": "d404d654-2ef9-44b3-a6e4-4b8934392239", 
	// timestamp of the event with milliseconds
	"ts": 1712570445333,
	"event_type": "engagement_impression",
	// user ext id prefixed with brand id
	"user_ext_id": "684:f21aaf49-54cf-4ff4-b3ce-146bd2535004", 
	"payload": {
		// Unique ID of the notification
		"engagement_uid": "f56883c4-2898-4388-a033-6205bbc41d8d",
		// smartico internal message_id 
		"message_id": 123456,
		// fixed constant for the 'Push' type of the communication
		"activity_type": 40
	}
}

Reporting action (click)

The event_body for the click should be built in the following way:

{
	// unique uuid for each event
	"uuid": "d404d654-2ef9-44b3-a6e4-4b8934392239", 
	// timestamp of the event with milliseconds
	"ts": 1712570445333,
	"event_type": "engagement_action",
	// user ext id prefixed with brand id
	"user_ext_id": "684:f21aaf49-54cf-4ff4-b3ce-146bd2535004", 
	"payload": {
		// Unique ID of the notification
		"engagement_uid": "f56883c4-2898-4388-a033-6205bbc41d8d",
		// smartico internal message_id 
		"message_id": 123456,
		// fixed constant for the 'Push' type of the communication
		"activity_type": 40,
		// link that user clicked
		"action": "https://mysite.com/link.html"
	}
}

Last updated 2 months ago