A PHP API to push pins to the pebble timeline
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

Readme.md

PHPebbleTimeline

About

PHPebbleTimeline is a library for making use the Timeline API through PHP.

Requirements

PHP 5.3 or Higher installed with cURL

Setup

Ensure your application is setup to use Pebble Timeline

Copy the TimelineAPI Folder to your project's directory.

Require the TimelineAPI in your project:

require_once 'PATH/TO/API/Timeline.php';

Creating and Customizing Pins - Objects

Pin Object

A Pin object represents the Timeline Pin which will be pushed to the watch.

To create a pin object be sure to use the Pin class

use TimelineAPI\Pin;

A Pin Object accepts the following parameters

Name Type Argument Default Description
id string (required) The ID that represents the pin
time DateTime (required) The UTC Datetime of the event
layout PinLayout (optional) null The description of the values of the pin
duration int (optional) null The duration of the event, in minutes
createNotification PinNotification (optional) null The notification the users sees when the pin is created
updateNotification PinNotification (optional) null The notification the user sees when the pin is already on their Timeline

Here is an example pin using a very generic PinLayout:

// Create the layout object for our pin
$genericLayout = new PinLayout(PinLayoutType::GENERIC_PIN, 'MY PIN TITLE', null, null, null, PinIcon::NOTIFICATION_FLAG);

//Create an instance of our pin
$pin = new Pin('MY-SAMPLE-PIN', (new DateTime('now')) -> now(new DateInterval('PT30M')), $genericLayout);
getID()

getID returns the string representation of your pin's ID.

//Returns 'MY-SAMPLE-PIN' for the above sample pin
$pin -> getID();
addReminder(PinReminder reminder)

addReminder adds a PinReminder to the Pin object. A maximum of 3 PinReminder objects can be added.

Returns true if the reminder was added; otherwise false

//Create the layout of the reminder
$reminderlayout = new PinLayout(PinLayoutType::GENERIC_REMINDER, 'Sample reminder!', null, null, null, PinIcon::NOTIFICATION_FLAG);

//Create the reminder objects
$reminderOne = new PinReminder($reminderlayout, (new DateTime('now')) -> now(new DateInterval('PT10M'))); // 20 mins before the sample event
$reminderTwo = new PinReminder($reminderlayout, (new DateTime('now')) -> now(new DateInterval('PT20M'))); // 10 mins before the sample event
...
$reminderFour = new PinReminder($reminderlayout, (new DateTime('now')) -> now(new DateInterval('PT28M'))); // 2 mins before the sample event

//Add the reminder objects
$pin -> addReminder($reminderOne); //returns true and is added
$pin -> addReminder($reminderTwo); //returns true and is added
...
$pin -> addReminder($reminderFour); //returns false and is not added
addAction(PinAction action)

addAction adds a PinAction to the Pin object. This action will be attached to the pin on the watch


//Create the PinAction objects
$actionOne = new PinAction('RSVP Yes', 1, PinActionType::OPEN_WATCH_APP); // Pin action to reply yes
$actionOne = new PinAction('RSVP No', 2, PinActionType::OPEN_WATCH_APP); // Pin action to reply no

//Add the reminder objects
$pin -> addAction($actionOne);
$pin -> addAction($actionOne);
getData()

getData returns an associative array of the pin's data

//Returns an array object representing all of the data added to our sample pin
$pin -> getData();

Layout Object

A PinLayout object represents the Layout Object which determine the styles of any views regarding your Pin on the Timeline.

To create a layout object be sure to use the PinLayout class

use TimelineAPI\PinLayout;

A PinLayout Object accepts the following parameters. Note that some optional parameters are required by certain PinLayoutTypes. More information available here: Layout Type

Name Type Argument Default Description
type PinLayoutType (required) The type of pin being displayed
title string (optional) null The main title of the pin when viewed
shorttitle string (optional) null The title of the pin in a compressed view
subtitle string (optional) null Shorter subtitle for the detailed view
body string (optional) null The notification the users sees when the pin is created
tinyicon PinIcon (optional) null The pin's tiny icon
smallicon PinIcon (optional) null The pin's small icon
largeicon PinIcon (optional) null The pin's large icon
foregroundColour PebbleColour (optional) null The main colour of the pin
backgroundColour PebbleColour (optional) null The background colour of the pin
headings Array (optional) null The text headings of the pin. The amount must match the amount of paragraphs
paragraphs Array (optional) null The text sections of the pin. The amount must match the amount of headings
lastupdated DateTime (optional) null The timestamp of when the pin's data (e.g. Weather forecast) was last updated
specialAttributes Array (optional) null Any special attributes that the speicifc layout may have. (e.g. sports score)

Here is an example pin using a very generic PinLayout:

// Create the layout object for our pin
$genericLayout = new PinLayout(PinLayoutType::GENERIC_PIN, 'MY PIN TITLE', null, null, null, PinIcon::NOTIFICATION_FLAG);
getData()

getData returns an associative array of the PinLayout's data

//Returns an array object representing all of the data added to our sample pin
$genericLayout -> getData();

Notification Object

A PinNotification object represents the Notification Object which will notify the user when a Pin changes status (created, updated).

To create a layout object be sure to use the PinNotification class

use TimelineAPI\PinNotification;

A PinNotification Object accepts the following parameters.

Name Type Argument Default Description
layout PinLayout (required) The layout of the notification which will be view by the user
time DateTime (optional) null The time the update was received

Here is an example notification.

$notificationLayout = new PinLayout(PinLayoutType::GENERIC_PIN, 'Pin updated', null, null, null, PinIcon::NOTIFICATION_FLAG);
$notification = new PinNotification($notificationLayout, new DateTime('now'));
getData()

getData returns an associative array of the PinNotification's data

$notification -> getData();

Reminder Object

A PinReminder object represents the Reminder Object which will send a reminder to the user at a specific time.

To create a reminder object be sure to use the PinReminder class

use TimelineAPI\PinReminder;

A PinReminder Object accepts the following parameters.

Name Type Argument Default Description
layout PinLayout (required) The layout of the notification which will be view by the user
time DateTime (optional) null The time the update was received

Here is an example reminder.

$reminderlayout = new PinLayout(PinLayoutType::GENERIC_REMINDER, 'Sample reminder!', null, null, null, PinIcon::NOTIFICATION_FLAG);
$reminder = new PinReminder($reminderlayout, new DateTime('now')); //send the reminder right away
getData()

getData returns an associative array of the PinReminder's data

$reminder -> getData();

Action Object

A PinAction object represents the Action Object which determine any actions your Pin may perform while on the Timeline.

To create an action object be sure to use the PinAction class

use TimelineAPI\PinAction;

A PinAction Object accepts the following parameters.

Name Type Argument Default Description
title String (required) The action title to be displayed in the pin's menu
launchcode int (required) The code to send your app when opening via this action
type [PinActionType] (required) The type of action being performed

Here is an example of a RSVP PinAction:

$action = new PinAction('RSVP Yes', 1, PinActionType::OPEN_WATCH_APP); // Pin action to reply yes
getData()

getData returns an associative array of the PinAction's data

//Returns an array object representing all of the data added to our action
$action -> getData();

Creating and Customizing Pins - Constants

PinLayoutType Constant

A PinLayoutType constant represents the Layout Types that are available. See available layouts for a list of all layout types supported. (If a layout is missing please let me know via the issue tracker!)

To retrieve layout types be sure to use the PinLayoutType class

use TimelineAPI\PinLayoutType;

The following code will get the layout type for a sports pin.

$layoutType = PinLayoutType::SPORTS_PIN;

PinIcon Constant

A PinIcon constant represents the Pin Icons available. See available icons for a list of all icons supported. (If an icon is missing please let me know via the issue tracker!)

To retrieve pin icons be sure to use the PinIcon class

use TimelineAPI\PinIcon;

The following code will get the URI for a Notification flag.

$icon = PinIcon::NOTIFICATION_FLAG;

PebbleColour Constant

A PebbleColour constant represents the Pebble Colours that are available. See available Colours for a list of all colours supported. (If a colour is missing please let me know via the issue tracker!)

To retrieve colours be sure to use the PebbleColour class

use TimelineAPI\PebbleColour;

The following code will get the colour code for red.

$colour = PebbleColour::RED;

PinActionType Constant

A PinActionType constant represents the Pin Actions that are available. See available action types for a list of all actions supported. (If an action is missing please let me know via the issue tracker!)

To retrieve actions be sure to use the PinActionType class

use TimelineAPI\PinActionType;

The following code will get the open action type.

$actionType = PinActionType::OPEN_WATCH_APP;

Pushing, Updating and Deleting Pins

Timeline Functions

All timeline functions are static methods and can be accessed via the Timeline class. Be sure to use this class.

use TimelineAPI\Timeline;
pushPin (String userToken, Pin pin)

Timeline::pushPin pushes a pin to the user's timeline. It requires a valid usertoken to target an individual user.

See responses for what responses will be returned. More information available at creating pins

Note that updating a pin uses this method as well. To update a pin push the id of the original pin.

$userToken = <Some valid userToken string>;
$pin = <some valid pin object>;
Timeline::pushPin($userToken, $pin);
pushSharedPin (String key, Array topics Pin pin)

Timeline::pushSharedPin pushes a pin to the the users' timelines. It requires a valid API key to send to multiple users. The parameter topics is an Array of type String containing all of the topics the pin should be pushed to. pin is the Pin to send to the users subscribed to those topics.

See responses for what responses will be returned. More information available at creating shared pins

$apiKey = <Your API key>;
$topics = ['Topic-1', 'Topic-2'];
$pin = <some valid pin object>;
Timeline::pushPin($apiKey, $topics, $pin);
deletePin (String userToken, String id)

Timeline::deletePin removes a pin to the the user's timeline. It requires a valid usertoken representing the watch that the pin should be removed from and the id of the pin to remove.

See responses for what responses will be returned. More information available at deleting pins

$userToken = <Some valid userToken string>;
$id = 'SAMPLE-PIN';
Timeline::deletePin($userToken, $id);
deleteSharedPin (String key, String id)

Timeline::deletePin removes a shared pin from all users' timelines. It requires a valid It requires a valid API key along with the id of the pin to be removed.

See responses for what responses will be returned. More information available at deleting shared pins

$apiKey = <Some valid userToken string>;
$id = 'SAMPLE-SHARED-PIN';
Timeline::deleteSharedPin($apiKey, $id);
listSubscriptions (String userToken)

Timeline::listSubscriptions lists all of a user's timeline subscriptions.

See responses for what responses will be returned. More information available at listing topics

$userToken = <Some valid userToken string>;
Timeline::listSubscriptions($userToken);

Timeline Responses

All Timeline functions return an associated array in the following form.

[status' => ['code' => RESPONSE_CODE, 'message' => RESULT_MESSAGE], 'result' => RAW_PEBBLE_RESULT]

status represents the overall status of the method called.

code is a valid response code

message is a valid response message

result is the raw JSON decoded object from the timeline