Need help with code_fund_ads?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

gitcoinco
338 Stars 95 Forks GNU Affero General Public License v3.0 1.3K Commits 37 Opened issues

Description

CodeFund is an open source platform that helps fund maintainers, bloggers, and builders through non-tracking ethical ads

Services available

!
?

Need anything else?

Contributors list

Maintainability All Contributors StackShare Join the conversation FOSSA Status codecov TODOs

CircleCI ERB Lint StandardRB Prettier-Standard


Logo

CodeFund Ads

CodeFund Ads is an ethical and discreet ad platform that funds open-source. It helps your favorite projects thrive by paying maintainers the majority of all generated revenue.

Table of Contents

Publisher JavaScript Embedding

After being approved on the CodeFund platform, publishers can add CodeFund ads to their site by including the CodeFund script and adding the CodeFund

div
.

Optional Query String Parameters

  • template
    - the template to use overrides the property config
  • theme
    - the theme to use overrides the property config
  • keywords
    - the keywords to use for targeting (comma delimited string) overrides the property config

Setting

async
on the script tag will ensure that CodeFund doens't block anything on the publisher's site.

Embed Callbacks

You may want to perform a function if the embed function does not return an ad.

To do this, you must create an event listener for the window event

codefund
.

Example

window.addEventListener("codefund", function(evt) {
  if (evt.detail.status !== 'ok') {
    console.log(evt.detail.status);
    // Do something
  }
});

Responses

On a successful embed,

evt.detail
will return:
{ "status": "ok", "house": false }

// or

{ "status": "ok", "house": true } // Ad returned is a house (fallback) ad

If an error occurs with embedding the ad,

evt.detail
will return:
{ "status": "error", "message": "error message" }

In the event that we do not have an available advertiser, and thus no available (paid or fallback) ad,

evt.detail
will return:
{ "status": "no-advertiser" }

API

The API is documented with Blueprint and is hosted on Apiary.

NOTE: Apairy doesn't fully adhere to the Blueprint 1A9 specification. Our Blueprint file may deviate from the spec to satisfy Apiary limitations.

The online version is generated from this file.

Ad Rendering and Impression/Click Tracking

The URLs/routes responsible for ad rendering are:

  • GET
    /properties/1/funder.js
    advertisements#show
    - embed script

This is the embed JavaScript that publishers place on their site. It includes the ad HTML and some logic to inject the HTML to the page and setup the links and impression pixel.

  • GET
    /scripts/76bfe997-898a-418c-8f0b-6298b7dd320a/embed.js
    advertisements#show
    - embed script

This endpoint is to support our legacy system (CodeFund v1) embed URLs. It points to the same endpoint as

/properties/1/funder.js
.
  • GET
    /display/76bfe997-898a-418c-8f0b-6298b7dd320a.gif
    impressions#show
    - creates an impression

This is the impression pixel image. The impression is created after this image is requested and served successfully. This means that a matching campaign was found and the embed JavaScript did its job correctly.

  • GET
    /impressions/76bfe997-898a-418c-8f0b-6298b7dd320a/click?campaign_id=1
    advertisement_clicks#show
    - creates a click

This is the proxy/redirect URL that allows us to track the click. We immediately redirect to the advertiser's campaign URL and background the work to mark the associated impression as clicked.

Development

If you'd like to use Docker to run the app, view that documentation here.

The following is for setting the app up on your local machine:

Prerequisites

You must create a (superuser) role with the name of your OS user in your postgres configuration in order to run db operations (e.g. testing and development).

Setup

# clone the repo & cd into the project
git clone https://github.com/gitcoinco/code_fund_ads.git
cd /path/to/code_fund_ads

setup environment variables

cp .env-example .env

If you need a password for your postgres role, uncomment "#export PGPASSWORD='' in the .env file and replace with the role's password

install dependencies

bundle install yarn install

db setup + tests

rails db:create db:migrate rails test

enable development caching

rails dev:cache

start app and navigate to http://localhost:3000

rails s

Development Caching

This application relies heavily on caching and will not work properly without the development cache enabled.

bundle exec rails dev:cache # => Development mode is now being cached.

Database

The

impressions
table will seed with approximately 100k records spread over 12 months by default. You can increase this by setting the
IMPRESSIONS
environment variable and seeding again.
IMPRESSIONS=10_000_000 rails db:seed

Maxmind

This product includes GeoLite data created by MaxMind, available from: http://www.maxmind.com

The GeoLite2-City.tar.gz is checked into this repo at

db/maxmind/GeoLite2-City.tar.gz

A fresh copy of the GeoLite2-City.tar.gz file can be obtained by running one of the following commands.

rails maxmind:download
DownloadAndExtractMaxmindFileJob.new.download

Workspace Setup

We provide a few example files for some popular tools to help you get up an running.

Tmux

SEE: sample config file

cd /path/to/code_fund_ads
./bin/tmuxinator

Teamocil

SEE: sample config file

cd /path/to/code_fund_ads
./bin/teamocil

Mert

SEE: sample config file

cd /path/to/code_fund_ads
./bin/mert

Code Standards

Enums

All enum values are managed as constants defined in

config/enums.yml
This file is converted to Ruby constants at runtime.

Introspect what enums are defined via the cli.

ENUMS.constants
ENUMS::USER_ROLES.constants
# etc...

Always use enums instead of "magic" values.

Linting

We avoid bike shedding by enforcing coding standards through tooling.

Ensure the code has been standardized by running the following before you commit.

./bin/standardize

Deployment

All pushes of master to Github result in a deployment to the staging environment. We use Herou build pipelines to promote the deployment to environments like production.

./bin/heroku_promote

Preboot

The application is configured for zero downtime deployments using Heroku's preboot feature.

This means that 2 versions of the application will be running simultaneously during deploys. All code changes should consider this deployment requirement to ensure that both versions of the app are valid and can run in parallel.

If breaking changes are unavoidable, disable preboot prior to deployment.

./bin/heroku_preboot_disable
./bin/heroku_promote
./bin/heroku_preboot_enable

Scheduler

There are several tasks that should be scheduled to run at different intervals. We manage this with Heroku Scheduler.

  • rails schedule:counter_updates
    - hourly
  • rails schedule:update_campaign_statuses
    - daily

Database

  • The
    impressions
    table is dynamically partitioned by advertiser (i.e.
    user
    ) and date
  • The database user requires permissions to execute DDL and create schema to support dynamic partition tables

Instrumentation

CodeFund uses a self-hosted version of count.ly to gather and analyze data. This data does not include any personal identifiable information.

The pattern in which to instrument CodeFund with is as follows:

CodeFundAds::Events.track(:action, :device_id, :segmentation)

Each variable can be the following value:

  • action
    - the label for the action being tracked (e.g.
    find_virtual_impression
    )
  • device_id
    - the session or unique ID of the visit
  • segmentation
    - hash of key value pairs that can be used to segment the data

The segmentation typically includes:

  • status
    - the status of the action (e.g.
    success
    or
    fail
    )
  • ip_address
    - the IP address of the visitor
  • property_id
    - the Property ID
  • campaign_id
    - the Campaign ID
  • creative_id
    - the Creative ID
  • country_code
    - the country code

Example:

# Application & Environment are added by default
CodeFundAds::Events.track("Find Virtual Impression", session.id, { status: "fail", ip_address: "127.0.0.1" })
CodeFundAds::Events.track("Find Fallback Campaign", session.id, {
  status: "success",
  ip_address: "127.0.0.1",
  property_id: 1,
  country_code: "US"
})

Candidates for GEM extraction

  • Searchable ActiveStorage metadata
  • Eventable

Contributors

Thanks goes to these wonderful people (emoji key):


Nathan Hopkins

💻 📖 🤔 🚇 📦 🔌 📆 👀 ⚠️ 🔧

Eric Berry

💻 🎨 📖 🤔 🚇 📦 📆 👀 ⚠️

Ron Cooke

💻 📖

Mike

📖

Arun Kumar

💻 📖

Maxim Dzhuliy

📖

Andrew Mason

💻 🎨 📖 🚇 👀 ⚠️ 🔧

Matt Glaman

💻 ⚠️

Aditya Anand M C

📖

dcd018

💻

Puru Dahal

💻

Curtis Mckee

⚠️ 💻 🎨

jeremiG

📖

Kashif Rafique

💻

Ethan

📖

XhmikosR

💻

Jason Barnabe

💻

Руслан Корнев

💻

This project follows the all-contributors specification. Contributions of any kind welcome!

License

AGPL-3.0

FOSSA Status

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.