Skip to content

Commit

Permalink
Merge pull request #26 from harman-goei/update-again
Browse files Browse the repository at this point in the history 
Update again
  • Loading branch information
Harman Goei committed Aug 5, 2016
2 parents 81eeb07 + 2d18985 commit 823c0be
Show file tree
Hide file tree
Showing 31 changed files with 529 additions and 481 deletions.
3 changes: 3 additions & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -70,3 +70,6 @@ crashlytics-build.properties

# TypeScript typings
typings/

# MacOS system files
.DS_Store
1 change: 1 addition & 0 deletions .nvmrc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
5.1
5 changes: 4 additions & 1 deletion .travis.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@ node_js:

before_install:
- npm install -g gulp
- export CHROME_BIN=chromium-browser
- export DISPLAY=:99.0
- sh -e /etc/init.d/xvfb start

script:
- gulp build
- gulp run-tests
299 changes: 126 additions & 173 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,227 +2,180 @@
[![Percentage of issues still open](http://isitmaintained.com/badge/open/prebid/Prebid.js.svg)](http://isitmaintained.com/project/prebid/Prebid.js "Percentage of issues still open")
[![Average time to resolve an issue](http://isitmaintained.com/badge/resolution/prebid/Prebid.js.svg)](http://isitmaintained.com/project/prebid/Prebid.js "Average time to resolve an issue")
[![Code Climate](https://codeclimate.com/github/prebid/Prebid.js/badges/gpa.svg)](https://codeclimate.com/github/prebid/Prebid.js)
[![Coverage Status](https://coveralls.io/repos/github/prebid/Prebid.js/badge.svg)](https://coveralls.io/github/prebid/Prebid.js)

Prebid.js
========
# Prebid.js

> Setup and manage header bidding advertising partners without writing code or confusing line items. Prebid.js is open source and free.
> A free and open source library for publishers to quickly implement header bidding.
Many SSPs, bidders, and publishers have all contributed to this project. [20+ Bidders](https://github.com/prebid/Prebid.js/tree/master/src/adapters) are supported by Prebid.js now.
This README is for developers who want to contribute to Prebid.js. For user-facing documentation, see [Prebid.org](http://prebid.org).

Check out the overview and documentation at http://prebid.org.
**Table of Contents**

No more week-long development. Header bidding is made easy by prebid.js :)
- [Install](#Install)
- [Build](#Build)
- [Run](#Run)
- [Contribute](#Contribute)

**Table of Contents**
<a name="Install"></a>

## Install

$ npm install

If you experience errors after a version update, try a fresh install:

$ rm -rf ./node_modules && npm cache clean && npm install

<a name="Build"></a>

## Build

To build the project on your local machine, run:

$ gulp build

This runs some code quality checks and generates the following files:

+ `./build/dev/prebid.js` - Full source code for dev and debug
+ `./build/dev/prebid.js.map` - Source map for dev and debug
+ `./build/dist/prebid.js` - Minified production code
+ `./prebid.js_<version>.zip` - Distributable zip archive

*Note:* You need to have `node.js` 4.x or greater installed to be able to run the `gulp build` commands.

### Build Optimization

The standard build output contains all the available bidder adapters listed in `adapters.json`.

You might want to exclude some/most of them from the final bundle. To make sure the build only includes the adapters you want, you can make your own adapters file.

For example, in `path/to/your/list-of-adapters.json`, write:

[
"openx",
"rubicon",
"sovrn"
]

Building with just these adapters will result in a smaller bundle which should allow your pages to load faster.

**Build standalone prebid.js**

- Clone the repo, run `npm install`
- Duplicate `adapters.json` to e.g. `list-of-adapters.json`
- Remove the unnecessary adapters from `list-of-adapters.json`
- Then run the build:

- [Prebid.js](#)
- [Usage](#usage)
- [Download the latest released code](#download-the-latest-released-code)
- [Example code](#example-code)
- [API](#api)
- [Contribute](#contribute)
- [Add a Bidder Adapter](#add-a-bidder-adapter)
- [install](#install)
- [Build](#build)
- [Configure](#configure)
- [Run](#run)
- [Unit Test In the Browser](#unit-test-in-the-browser)
- [Supported Browsers](#supported-browsers)
$ gulp build --adapters path/to/your/list-of-adapters.json

**Build prebid.js using NPM for bundling**

In case you'd like to explicitly show that your project uses `prebid.js` and want a reproducible build, consider adding it as an `npm` dependency.

- Install `prebid.js` as an `npm` dependency of your project
- Duplicate `node_modules/prebid.js/adapters.json` to under your project path, e.g. `path/to/your/list-of-adapters.json`
- Remove the unnecessary adapters
- Run the `prebid.js` build under the `node_modules/prebid.js/` folder

$ gulp build --adapters path/to/your/list-of-adapters.json

Most likely your custom `prebid.js` will only change when there's:

- A change in your list of adapters
- A new release of `prebid.js`

Usage
----------
Download the integration example [here](https://github.com/prebid/Prebid.js/blob/master/integrationExamples/gpt/pbjs_example_gpt.html).
Having said that, you are probably safe to check your custom bundle into your project. You can also generate it in your build process.

### Download the latest released code ###
[See the releases page here](https://github.com/prebid/Prebid.js/releases) and download a copy.
<a name="Run"></a>

### Example code ###
## Run

To configure Prebid.js to run locally, edit the example file `./integrationExamples/gpt/pbjs_example_gpt.html`:

1. Change `{id}` values appropriately to set up ad units and bidders
2. Set the path to Prebid.js in your example file as shown below (see `pbs.src`).

For development:

**Include the prebid.js library**
Note that you need to host `prebid.js` locally or on a CDN and update the reference in the code snippet below for `cdn.host.com/prebid.min.js`
```javascript
(function () {
var d = document;
var pbs = d.createElement('script');
(function() {
var d = document, pbs = d.createElement('script'), pro = d.location.protocol;
pbs.type = 'text/javascript';
//replace with your CDN hosted version. HTTPS is strongly recommended.
pbs.src = '//cdn.host.com/prebid.min.js';
var target = d.getElementsByTagName('script')[0];
target.parentNode.insertBefore(pbs, target);
pbs.src = ((pro === 'https:') ? 'https' : 'http') + './build/dev/prebid.js';
var target = document.getElementsByTagName('head')[0];
target.insertBefore(pbs, target.firstChild);
})();
```

**Setup ad units**
```javascript
pbjs.que.push(function(){
var adUnits = [{
code: '{id}',
sizes: [[300, 250], [300, 600]],
bids: [
{
bidder: 'appnexus',
params: {
placementId: '{id}'
}
}
]
}];
//add the adUnits
pbjs.addAdUnits(adUnits);
});
```
For deployment:

**Request Bids**
```javascript
pbjs.que.push(function(){
pbjs.requestBids({
bidsBackHandler: function(bidResponses) {
//do stuff when the bids are back
}
})
});
(function() {
var d = document, pbs = d.createElement('script'), pro = d.location.protocol;
pbs.type = 'text/javascript';
pbs.src = ((pro === 'https:') ? 'https' : 'http') + './build/dist/prebid.js';
var target = document.getElementsByTagName('head')[0];
target.insertBefore(pbs, target.firstChild);
})();
```

**See Console Debug Errors during testing**
By default console errors are suppressed. To enabled add `?pbjs_debug=true` to the end of the URL
for testing.
To run the project locally, use:

API
----------
Full Developer API reference:
$ gulp serve

[Click here to access the API](http://prebid.org/dev-docs/publisher-api-reference.html)
This runs code quality checks, generates all the necessary files and starts a web server at `http://localhost:9999` serving from the project root. Navigate to your example implementation to test, and if your `prebid.js` file is sourced from the `./build/dev` directory you will have sourcemaps available in your browser's developer tools.

Contribute
----------
**Note:** You need to have at least `node.js 4.x` or greater installed to be able to run the gulp build commands.
To run the example file, go to:

### Add a Bidder Adapter ###
Follow the [guide outlined here](http://prebid.org/dev-docs/bidder-adaptor.html) to add an adapter.
+ `http://localhost:9999/integrationExamples/gpt/pbjs_example_gpt.html`

### Install ###
$ npm install
To view a test coverage report, go to:

If you experience errors, after a version update, try a fresh install:
+ `http://localhost:9999/build/coverage/karma_html/report`

$ rm -rf ./node_modules && npm cache clean && npm install
A watch is also in place that will run continuous tests in the terminal as you edit code and tests.

### Build ###
$ gulp build
<a name="Contribute"></a>

Runs code quality checks, generates prebid.js files and creates zip archive distributable:
## Contribute

- `./build/dev/prebid.js` Full source code for dev and debug
- `./build/dev/prebid.js.map` Source map for dev and debug
- `./build/dist/prebid.js` Minified production code
- `./prebid.js_<version>.zip` Distributable
Many SSPs, bidders, and publishers have contributed to this project. [20+ Bidders](https://github.com/prebid/Prebid.js/tree/master/src/adapters) are supported by Prebid.js.

Code quality is defined by `./.jscs` and `./.jshint` files and errors are reported in the
terminal. The build will continue with quality errors, however. If you are contributing code
you can configure your editor with the provided .jscs and .jshint settings.
### Add a Bidder Adapter

### Optimisation ###
To add a bidder adapter, see the instructions in [How to add a bidder adaptor](http://prebid.org/dev-docs/bidder-adaptor.html).

The standard build output contains all the available adapters which are listed in `adapters.json`.
### Code Quality

You might want to exclude some/most of them from the final bundle and specifically define the ones you're interested in.
Code quality is defined by `.jscs` and `.jshint` files and errors are reported in the terminal.

```json
// Example: path/to/your/list-of-adapters.json
[
"openx",
"rubicon",
"sovrn"
]
```
If you are contributing code, you should configure your editor with the provided `.jscs` and `.jshint` settings.

This will result in a smaller, optimised bundle which might allow your pages to load faster.
### Unit Testing with Karma

**Build standalone prebid.js**

- clone repo, run `npm install`
- duplicate `adapters.json` to e.g. `list-of-adapters.json`
- remove the unnecessary adapters from `list-of-adapters.json`
- then run build

$ gulp build --adapters path/to/your/list-of-adapters.json
$ gulp test --watch

**Build prebid.js using NPM for bundling**
This will run tests and keep the Karma test browser open. If your `prebid.js` file is sourced from the `./build/dev` directory you will also have sourcemaps available when using your browser's developer tools.

In case you'd like to explicitly show that your project uses `prebid.js` and want a reproducible build, consider adding it as an `npm` dependency.
+ To access the Karma debug page, go to `http://localhost:9876/debug.html`

- install `prebid.js` as an `npm` dependency of your project
- duplicate `node_modules/prebid.js/adapters.json` to under your project path
e.g. `path/to/your/list-of-adapters.json`
- remove the unnecessary adapters
- run the `prebid.js` build under `node_modules/prebid.js/` folder

$ gulp build --adapters path/to/your/list-of-adapters.json

Most likely your custom `prebid.js` will only change when there's

- a change in your list of adapters
- a new release of `prebid.js`

having said that, you are probably safe to check in your custom bundle into your project, or you can generate it in your build process.

### Configure ###
Edit example file `./integrationExamples/gpt/pbjs_example_gpt.html`:

1. Change `{id}` values appropriately to set up ad units and bidders.

1. Set path for prebid.js in your example file:
#####Development `pbs.src = './build/dev/prebid.js';` #####
```javascript
(function() {
var d = document, pbs = d.createElement('script'), pro = d.location.protocol;
pbs.type = 'text/javascript';
pbs.src = ((pro === 'https:') ? 'https' : 'http') + ':./build/dev/prebid.js';
var target = document.getElementsByTagName('head')[0];
target.insertBefore(pbs, target.firstChild);
})();
```
#####Test/Deploy (default) `pbs.src = './build/dist/prebid.js';`#####
```javascript
(function() {
var d = document, pbs = d.createElement('script'), pro = d.location.protocol;
pbs.type = 'text/javascript';
pbs.src = ((pro === 'https:') ? 'https' : 'http') + './build/dist/prebid.js';
var target = document.getElementsByTagName('head')[0];
target.insertBefore(pbs, target.firstChild);
})();
```

### Run ###
+ For test results, see the console

$ gulp serve
+ To set breakpoints in source code, see the developer tools

This runs code quality checks, generates prebid files and starts a webserver at
`http://localhost:9999` serving from project root. Navigate to your example implementation to test,
and if your prebid.js file is sourced from the `./build/dev` directory you will have sourcemaps
available in browser developer tools.
Detailed code coverage reporting can be generated explicitly with

Navigate to `http://localhost:9999/integrationExamples/gpt/pbjs_example_gpt.html` to run the
example file.
$ gulp test --coverage

Navigate to `http://localhost:9999/build/coverage/karma_html/report` to view a test coverage report.
The results will be in

A watch is also in place that will run continuous tests in the terminal as you edit code and
tests.
./build/coverage

### Unit Test In the Browser ###
$ gulp test --watch
*Note*: Starting in June 2016, all pull requests to Prebid.js need to include tests with greater than 80% code coverage before they can be merged. For more information, see [#421](https://github.com/prebid/Prebid.js/issues/421).

This will run tests and keep the Karma test browser open. If your prebid.js file is sourced from
the build/dev directory you will also have sourcemaps available when viewing browser developer
tools. Access the Karma debug page at:
`http://localhost:9876/debug.html`
View console for test results and developer tools to set breakpoints in source code.
For instructions on writing tests for Prebid.js, see [Testing Prebid.js](http://prebid.org/dev-docs/testing-prebid.html).

Detailed code coverage reporting can be generated explicitly with `$ gulp test --coverage` and
results found in `./build/coverage`.
### Supported Browsers

### Supported Browsers ###
Prebid.js is supported on IE9+ and modern browsers.

0 comments on commit 823c0be

Please sign in to comment.