Skip to content

Latest commit

 

History

History
70 lines (49 loc) · 5.43 KB

README.md

File metadata and controls

70 lines (49 loc) · 5.43 KB
Raw

Action Network SDK

simple php SDK for Action Network API v. 2
Version 1.2, October 2016

author: Jonathan Kissam

This is not a full SDK for the Action Network API. It provides a method to call an arbitrary endpoint, and also supports:

  • traversing collections of Action Network resources with a callback function
  • pushing new supporters into a client's Action Network database
  • pulling lists of petitions, forms, events and tags
  • tagging supporters and adding them to petitions, forms, and events.

It was primarily developed for use in my Action Network Wordpress plugin and webform_external Drupal module

Sign up for my email list to receive updates about new versions and applications.

If you find this SDK useful, please consider supporting further development by hiring me or making a donation.

Please contact me with bug reports, feedback, thoughts or feature requests.

Updates

October 6, 2016:

  1. Updated to address the fact that Action Network's API removed the total_pages field from the "people" collection on 9/2/2016. getFullSimpleCollection and traverseFullCollection should now work with the "people" endpoint, although that is probably not a good practice, for the same reason that Action Network removed the field from the collection (i.e., for any large collection, it is probably better to use traverseCollection with the new getNextpage method in a batching function, to prevent php timeouts).

  2. Added getNextPage method, to return the _links->next->href property from a collection (to aid in traversing collections which return multiple pages).

  3. Modified the getResourceTitle method to return the email address for the "people" collection, since a "person" resource has neither "title" nor "name," and the email address is unique, required, and more important than the actual name.

ActionNetwork class

This SDK contains an ActionNetwork class, which creates an Action Network API connection controller. It has the following methods:

  • call: Makes an API call. Pass an endpoint, an optional HTTP method (defaults to "GET"), and a php object which will be converted into JSON. Returns a php object version of the JSON returned from Action Network's API
  • traverseCollection and traverseFullCollection: Pass a collection endpoint (such as "events") and a callback function, and the method will iterate through the embedded resources in the collection, passing each one to the callback function, along with the endpoint, a numerical index, and the total number of records in that collection. traverseFullCollection will iterate through all pages in the collection, while traverseCollection will only iterate through a single page. The callback function can either be a method of a class that extends ActionNetwork, or a standalone function. If the latter, the callback function will also be passed the ActionNetwork object.
  • getEmbedCodes: fetch embed codes for a particular resource
  • getAllPetitions, getAllForms, getAllEvents and getAllTags: fetch simple lists of resources (ids and titles/names)
  • signupPerson, recordAttendance, recordSignature and recordSubmission: use Action Network's helper API endpoints to add supporters, and add them to petitions, forms and events. All of these methods take an Action Network Person (see below), the event/petition/form helpers take the id of the relevant event, petition or form as a second argument, recordSignature takes an optional comment as a third argument, and all of these functions can take an array of tags (which must already exist in the system) as a final argument
  • getCollection, getSimpleCollection and getFullSimpleCollection: helper functions for dealing with paging
  • getResourceId, getResourceTitle and simplifyCollection: helper functions for simplifying collections into lists of ids and titles

ActionNetworkPerson class

The SDK also contains an ActionNetworkPerson class, which creates a well-formed person object which can be passed to Action Network's API. There are three methods to instantiate the class:

  1. Pass a php object which follows the schema
  2. Pass a php associative array which follows the schema.
  3. Pass a simple php object or associative array with some or all of the following properties/keys:
  • email
  • status ('subscribed', 'unsubscribed', 'bouncing', or 'spam complaint')
  • given_name
  • family_name
  • address_lines
  • locality
  • region
  • postal_code
  • country

In addition, any properties or (first-level) array values which are simple strings will be treated as custom fields

The class will enforce receiving a valid email address, but in order to work with the API, it also must receive a postal code.

The class also has the following methods, which should be fairly self-explanatory:

  • setSubscriptionStatus: takes a string ('subscribed', 'unsubscribed', 'bouncing', or 'spam complaint')
  • addFamilyName: takes a string
  • addGivenName: takes a string
  • addPostalAddress: takes a well-formed postal address
  • addCustomField: takes two strings (key, value), or an associative array