Necessary third party integrations

Right now, there are several third party integrations that Champaign depends on (and will not work properly without). We'd love to work around third party dependencies in a way that allows you to either plug in a third party service or a service that you host and maintain yourself, but with our limited capacity, we haven't been able to maintain the application in such a way. Should you want to help us with that work, please get in touch.

The third party services Champaign needs to operate right now are:

• ActionKit - at SumOfUs, we use ActionKit to send our mailings, and our analysts use the ActionKit database for their queries
• ShareProgress - you can find their API docs here - for optimizing Facebook, Twitter and email shares
• Payment processors:
  • Braintree - for card payments (debit/credit)
  • GoCardless - for direct debit payments

ActionKit

We use ActionKit to send our mailings to our mailing lists, and our analysts use a replica of the data on the ActionKit database to run queries. Because of that, all of the action data on Champaign is denormalized over to ActionKit into tables / columns agreed upon with the analysts. For example, whenever a campaigner creates a page on Champaign, a petition and a donation page resource is created on ActionKit that the actions (e.g. petition signatures or donations) are recorded against. The mailing that campaigners set up and send through ActionKit links to the Champaign page and the actions that our members take on the page are recorded both on the Champaign postgres database as well as on the page resources associated with the pages' donation and petition page resources on ActionKit.

Champaign integrates with ActionKit directly through the ActionKit REST API, as well as by publishing events to a fifo queue hosted on AWS SQS. From there, a separate worker (the champaign-ak-worker) processes the messages against the ActionKit API. Many events are processed through the queue in order to improve user interaction. Sometimes, ActionKit takes a long time to process a request, or returns a random 500 response from the API. Having the separate worker allows us to automatically retry randomly failed requests, ensures that both members' and campaigners' user experience doesn't suffer from long processing times, and allows us to persist pending requests against the API whenever processing against ActionKit fails for a longer time for a reason or another (in this case the messages simply land on the dead letter queue which we can process once the issue has been resolved).

Despite having this external service to communicate with ActionKit, Champaign still needs to access ActionKit's API directly in a couple of cases, that's why you'll need to configure AK credentials in order to run Champaign. You'll be able to do this using environment variables in production.

For local development, you don't need to run the champaign AK processor - you can simply set the AK credentials in config/settings.development.local.yml.

ShareProgress

ShareProgress (SP) is a service that allows you to create multiple versions of three share types (Facebook, Twitter and Email shares). It serves the shares for you and uses a multi armed bandit algorithm to direct different amounts of traffic to the different share variant, eventually almost exclusively serving the variant that has performed the best. Champaign interacts with ShareProgress through the SP REST API for which we have a wrapper gem.

Look into the ShareProgress API docs for an explanation of their class abstractions (they notions of variants and buttons are pretty much duplicated for share abstractions in Champaign).

We also host a service that periodically fetches ShareProgress analytics and updates the numbers on the share variants persisted in Champaign.

Champaign also supports creating WhatsApp shares, but those are not served through ShareProgress and have no multi armed bandit to support them. Traffic is directed to them at random and campaigners need to delete the less performant shares if they want to 'promote' a share variant that is doing better. You can look at how the WhatsApp shares are created and served if you want to introduce a new share type.

For local development, you will need to have the ShareProgress API key configured in your development.local.yml.

Payment processors

The payment processors are covered in more detail in their own section on this wiki page.