Outlast

Outlast Apps - Notifications & Invites

The Outlast Apps notifications plugin allows you to send push notifications to Facebook and/or mobile apps. There are a few things to consider before sending notifications:

Only Facebook Canvas Apps support notifications and invites. You must have a namespace and add the Canvas App platform in the Facebook developer panel.
For Facebook Tab Apps, you need to have a canvas app running in addition to the tab app. All invites are directed to the tab app. Redirections are against FB policy but it is technically possible (see below).

Sending Facebook Invites

You can send invite with the oa.request(name, description, url) method, where:
string name is the application name,
string description is the description and
string url is the URL of the application (or a specific page).

Sending Facebook notifications

You can send one-off Facebook notifications to a specific recipient via the oaapp object. Here’s a sample code:

// Make sure the user is logged in (fbuser exists)
  $this->baseapp->login();
// Send notification
  $this->zajlib->variable->oaapp->notification($this->zajlib->variable->fbuser->fbid, "Hi, this is an important notification", "&page=landing")

The link must be relative to the canvas page, so &page=landing would be a valid entry for a typical OaApp. If you leave the link parameter empty, the user will be taken to the front page.

Also, remember that apps must have a canvas url set up or notifications will not be delivered. No error will be displayed, they will simply not arrive. Notifications also have a less than 180 character limit – with utf characters it is less than the documented 180 chars. Again, with more than the limit no errors are displayed, notifications simply do not arrive.

Setting up push notifications

Push notifications are enabled through the admin interface when the Outlast Apps plugin is installed. You must however set up the plugin’s autorun script to run via your server’s cron job service. The frequency is up to you but running it once a minute is reasonable. By default, 100 notifications are sent out during each autorun script instance.

Creating, sending, managing push notifications

This is done through the admin interface. Here are some restrictions:

The url associated with the notification needs to be relative to the canvas app’s base url. Leave it empty to send users to the canvas app’s home page (base url)
Notification text is limited to 180 characters, but this is counted in a strange UTF-encoded way, so test it first to make sure it works if you are using international characters.

Setting up custom group filters

You may want to send only to a subset of users at a time. Custom group filters allows you to define completely unique groups which can then be selected in the admin interface for segmented sending.

In order to create custom groups you will need to create the __notification_groups magic method. The method should be placed within the app’s custom controller and should return a single, multi-dimensional array. The array has the following structure:

/* Place this in the app's custom controller */
public function __notification_groups(){
  return array(
	'group1id'=>array(
			'name'=>'Name of group 1',
			'callback'=>function($f){
				// Filter users to group one
					$users = FacebookUser::fetch()->full_query("SELECT DISTINCT fbuser AS id FROM oaphoto ...custom SQL");
				return $users;

			}
		),
	'featured'=>array(
			'name'=>'Featured users',
			'callback'=>function($f){
				// Filter users that have a star (group two)
					$f->filter('featured', true);
				return $f;
			}
	)
  );
}

Setting up custom notification actions

The default action when sending notifications is to send push notifications (via Facebook or mobile).

However you can set up custom notification actions. This allows you to perform custom actions for each user, for example send an email to them, send an SMS, etcetc.

You need to be careful that the object passed to the callback can be multiple different types: it might be FacebookUser but it could also be an OaEmailList.

The syntax is very similar to the way you set up custom groups:

/* Place this in the app's custom controller */
public function __notification_actions(){
  return array(
	'action1id'=>array(
			'name'=>'Send a winner email',
			'description'=>'Sends winner notification email to user.',
			'callback'=>function($fbuserORoaemaillist){
				// Send the email
					zajLib::me()->template->email(..)
				// You should return true if it was successful, an error message (string) otherwise
				return true;
			}
		),
	'actionsmsid'=>array(
			'name'=>'Send a reminder SMS',
			'description'=>'Sends Dont forget to do something! sms to user.',
			'callback'=>function($fbuserORoaemaillist){
				// Send an SMS
					// connect to Twilio, etc.
				// You should return true if it was successful, an error message (string) otherwise
				return true;
			}
	)
  );
}

Redirect users to tab apps

If you want the canvas features above but would like to have your app run within a Facebook Page (as a tab app) instead, you need to set up a proper redirect from your canvas app to your tab app. Just include the following code in your app’s base.html.

Warning! Redirecting from canvas to tab is against Facebook rules. Use with care!

Plugins