Altruisto.com Chrome Extension Documentation


Overview


What is altruisto.com Chrome Extension?

It's a simple browser extension that allows user to effortlessly raise money for charities. When you're surfing the internet you can just click a button and a portion of money you spend on given site will be donated to charities (the prices do not change for you).

How does it work?

There are three features right now:
  1. the main one is displaying a bar at the top of user's browser that allows her to start raising money for charities by purchasing products in the online store their are currently browsing
  2. addiotionally, there is a suggestion box - a 250px x 400px square that shows up in the bottom right of user's browser and informs the user that there is either a better price for given product, a copoun that they may use, some kind of promotion, or just some really good product they may be intersted in.
  3. lastly, there is a feature that changes plain text URLs into clickable links. If the user clicks on it and decides to buy something, certain percentage of their spendings will be sent to charities.

What are the benefits for the user?

The main benefit is that user can effortlessly and immediatly start helping to make World a better, more fair and hospitable place.

What are the benefits for online stores?

For one, the extension gives people extra motivation to buy in one of our affiliate stores vs. a competitor who is not an affiliate (since buying in the affiliate shop equals raising money for charities). Additionally, the two extra features generate more traffic for the stores (in the case of “suggestion box” - assuming that they offer competitive prices).


Main feature - Top Bar

Here's a preview:

This feature uses both content.js and background.js files. It first checks if the feature is turned on by accessing options saved in storage.sync API by options.html file.

if(items.addTopBar)

It is turned on by default. See below:

chrome.storage.sync.get({ createLinksFromPlaintext: true, addSuggestionBox: true, addTopBar: true }, function(items){

Next, it verifies wether the user is viewing a page that belongs to one of our affiliates. We use isOurFavouritePartner() function to asses that and pass location.href argument.

if(isOurFavouritePartner(location.href)){

The function checks if the domain of given URL is in the Array ourFavouritePartnersWeLoveYouGuys which includes the domains of all affiliates to agreed to be a part of this feature of our extension. If user is indeed viewing our affiliate's website we add an invisible div to the DOM and a style element that makes the top bar look nicer :) The div is invisible to not create this effect where for a split second the bar is empty and a moment after that the rest of the code fills the bar with appropriate content. It just seems to be bad (not smooth) UX.

Next, it retrieves a list of affiliates' pages that the user has already visited and decided to raise money from as well as list of pages on which user has closed the topbar. These lists are stored in storage.local API. We don't want to use storage.sync API since the affiliate mechanism works based on cookies that are stored locally not synchronically.

chrome.storage.local.get({activatedAffiliates: [], closedWebsites: []}, function(itemsLocal) {

If the user has previously clicked on "x" icon to close the topbar on this website, we do not show him the top bar. The list of closed websites is cleared every 7 days by background.js.

If the user has already activated raising money from current page and it happened less than 7 days ago we show them a top bar with an option to deactivate raising money from this website. It looks like that:

Otherwise (and by default) we show a top bar with an option to activate raising money from current website. We use the 7 days deadline to ensure that the cookies have not yet expired. 7 days should cover most of the affiliates' cookies expiration time, however there are some that store cookies just for one day so in the future that should probably be improved.

After figuring out which top bar version should be shown (activate or deactivate raising money from current website) we update the content of a bar and make it visible.

If user clicks "start raising money" button, she is redirected to https://altruisto.com/confirm?url=example.com where she can confirm that she indeed wants to activate affiliate program on given page. She does that by clicking on the button that redirects her to https://altruisto.com/redirect?url=example.com at which point two things happen: 1) background.js runs a code that saves example.com to the list of activated affiliate websites; 2) PHP script makes an affiliate URL based on provided address and redirects the user to that URL.

If user clicks "stop raising money" button, three things happen: 1) content.js sends a request to background.js to delete cookies from given domain (to ensure that affiliate tracking cookie does not exist any longer) 2) background.js also deletes the website's domain from list of activated affiliates 3) content.js changes topbar to show "start raising money" button (so the user can again raise money with that website).


Feature #2 - Suggestion box

Here's how it looks:

This feature uses only content.js file. Similarly to previous option, it first checks if the feature is turned on by accessing extension's options saved in local.storage API.

It runs only on pages where top bar is not shown, since showing both top bar and suggestion box seems little bit too much (bad overall UX).

The suggestions are presented based on page title, therefore first we check if current page has any title at all. If so we then make a call to altruisto.com API which returns a suggestion to show based on page's title. The suggestion data from API is returned in JSON format and passed to addSuggestionBox() function.


Feature #3 - Changing plaintext links into clickable affiliate links

This feature uses only content.js file. First it retrieves extension options saved in storage.sync API by options.html file. It runs walk() function and passes the retreieved extension options to that function.

walk() analyzes all child nodes of document.body node. If certain node's type equals 3 it means it's text. We then make sure that it's not a text of an anchor (a tag) and then we use findAndReplaceDOMText class by padolsey and createAnchorFromString() function to change a plaintext URL into clickable affiliate link.


content.js