prebid/Prebid.js

[](https://isitmaintained.com/project/prebid/Prebid.js "未解决问题百分比") [](https://coveralls.io/github/prebid/Prebid.js?branch=master) # Prebid.js 本 README 面向希望为 Prebid.js 做出贡献的开发者。 更多文档可在 [Prebid.js 文档主页](https://docs.prebid.org/prebid/prebidjs.html) 找到。 工作示例可在 [开发者文档](https://prebid.org/dev-docs/getting-started.html) 中找到。 Prebid.js 是免费提供以方便使用的开源软件。虽然它旨在帮助公司满足与 header bidding 相关的法律要求，但我们无法也不保证您使用 Prebid.js 将满足法律要求。您有责任确保您对 Prebid.js 的使用符合所有适用法律。我们强烈建议您在 Prebid.js 时获取法律建议，以确保您的实施符合您运营所在地区的所有法律。 **目录** - [用法](#Usage) - [安装](#Install) - [构建](#Build) - [运行](#Run) - [贡献](#Contribute) ## 用法（作为 npm 依赖） **注意**：v10 之前的版本在作为 NPM 依赖使用时需要配置一些 Babel 插件 - 请参阅 [v9 README](https://github.com/prebid/Prebid.js/blob/9.43.0/README.md)。另请参阅 [自定义构建选项](#customize-options) ``` import pbjs from 'prebid.js'; import 'prebid.js/modules/rubiconBidAdapter'; // imported modules will register themselves automatically with prebid import 'prebid.js/modules/appnexusBidAdapter'; pbjs.processQueue(); // required to process existing pbjs.queue blocks and setup any further pbjs.queue execution pbjs.requestBids({ ... }) ``` 您可以从 `types.d.ts` 导入每个模块的类型定义，从 `global.d.ts` 导入 `pbjs` 全局变量的类型定义： ``` import 'prebid.js/types.d.ts'; import 'prebid.js/global.d.ts'; pbjs.que.push(/* ... */) ``` 或者，如果您的 Prebid bundle 使用不同的全局变量名称： ``` import type {PrebidJS} from 'prebid.js/types.d.ts'; declare global { interface Window { myCustomPrebidGlobal: PrebidJS; } } ``` ### 自定义构建选项 Prebid.js 允许您设置以下构建选项： | 名称 | 类型 | 描述 | 默认值 | | ---- | ---- | ----------- | ------- | | globalVarName | String | Prebid 全局变量名称 | `"pbjs"` | | defineGlobal | Boolean | 如果为 false，则不设置全局变量 | `true` | | distUrlBase | String | 用于动态加载模块的基础 URL（例如 debugging-standalone.js） | `"https://cdn.jsdelivr.net/npm/prebid.js/dist/chunks/"` | 这些选项可以通过 webpack loader 或 Rollup 兼容插件进行自定义。 有关详细信息和示例，请参阅 [自定义构建选项](customize/README.md)。 ## 安装 ``` $ git clone https://github.com/prebid/Prebid.js.git $ cd Prebid.js $ npm ci ``` *注意*：您需要安装 `NodeJS` 12.16.1 或更高版本。 *注意*：在 Prebid.js 的 1.24.0 版本中，我们从使用 gulp 3.9.1 过渡到使用 gulp 4.0。为了符合 gulp 对 4.0 的推荐设置，您需要在运行通用的 `npm ci` 之前全局安装 `gulp-cli`。这不应该影响您可能使用的在设置中使用早期版本 gulp 的任何其他项目。 如果您之前全局安装了 `gulp` 的版本，您需要在安装 `gulp-cli` 之前将其移除。您可以通过运行 `gulp -v` 并查看输出的 `CLI` 字段中列出的版本来检查是否已安装。如果您全局安装了 `gulp` 包，它可能与您在 `Local` 字段中看到的版本相同。如果您已经安装了 `gulp-cli`，它应该是较低的主版本（在过渡时版本为 `2.0.1`）。 要移除旧包，您可以使用命令：`npm rm gulp -g` 设置完成后，运行以下命令全局安装 `gulp-cli` 包：`npm install gulp-cli -g` ## 开发构建 要在本地机器上构建项目，我们建议运行： ``` $ gulp serve-and-test --file ``` 这将运行测试但不运行 linting。将在 `http://localhost:9999` 启动一个 Web 服务器，从项目根目录提供以下文件： + `./build/dev/prebid.js` - 用于开发和调试的完整源代码 + `./build/dev/prebid.js.map` - 用于开发和调试的 source map + `./build/dev/prebid-core.js` + `./build/dev/prebid-core.js.map` 开发可能会稍慢一些，但如果您更喜欢 linting 和额外的监视文件，您仍然可以只运行： ``` $ gulp serve ``` ### 构建优化 标准构建输出包含 `modules` 文件夹中所有可用模块。但请注意，有些 bid adapter 通过别名支持多个 bidder，因此如果您在 modules 文件夹中没有看到某个 bid adapter 的文件，您可能需要 grep 仓库以找到需要包含的模块名称。 您可能希望从最终 bundle 中排除其中一些/大部分模块。要确保构建仅包含您想要的模块，您可以使用 `--modules` CLI 参数指定要包含的模块。 例如，运行 serve 命令时：`gulp serve --modules=openxBidAdapter,rubiconBidAdapter,sovrnBidAdapter` 仅使用这些 adapter 进行构建将产生更小的 bundle，这应该可以让您的页面加载更快。 **构建独立的 prebid.js** - 克隆仓库，运行 `npm ci` - 然后运行构建： $ gulp build --modules=openxBidAdapter,rubiconBidAdapter,sovrnBidAdapter 或者，可以指定一个包含您想要包含的模块列表的 `.json` 文件。 ``` $ gulp build --modules=modules.json ``` 其中 `modules.json` 包含以下内容 ``` [ "openxBidAdapter", "rubiconBidAdapter", "sovrnBidAdapter" ] ``` **使用 npm 构建 prebid.js 进行打包** 如果您想明确显示您的项目使用 `prebid.js` 并希望获得可重现的构建，请考虑将其添加为 `npm` 依赖。 - 将 `prebid.js` 添加为您的项目的 `npm` 依赖：`npm install prebid.js` - 在 `node_modules/prebid.js/` 文件夹下运行 `prebid.js` 构建 $ gulp build --modules=path/to/your/list-of-modules.json 您的自定义 `prebid.js` 最有可能在以下情况下才会更改： - 您的模块列表发生变化 - `prebid.js` 有新版本发布 话虽如此，您可以安全地将自定义 bundle 检入您的项目。您也可以在构建过程中生成它。 **构建一次，多次打包** 如果您需要从同一个 Prebid 版本生成多个不同的 bundle，您可以使用以下命令重用单次构建： ``` gulp build gulp bundle --tag one --modules=one.json gulp bundle --tag two --modules=two.json ``` 这会生成稍大的文件，但优点是运行速度更快（在初始 `gulp build` 之后）。这也是 [Prebid.org 下载页面](https://docs.prebid.org/download.html) 使用的方法。 ### 从构建中排除特定功能 从版本 7.2.0 开始，您可以指示构建排除某些功能的代码 - 例如，如果您不需要原生广告支持： ``` gulp build --disable NATIVE --modules=openxBidAdapter,rubiconBidAdapter,sovrnBidAdapter # substitute your module list ``` 可以通过这种方式禁用的功能包括： - `VIDEO` - 支持视频出价； - `NATIVE` - 支持原生出价； - `UID2_CSTG` - 支持 UID2 客户端令牌生成（请参阅 [Unified ID 2.0](https://docs.prebid.org/dev-docs/modules/userid-submodules/unified2.html)) - `GREEDY` - 禁用 Prebid 中使用阻塞的"贪婪" Promise（请参阅 [说明](#greedy-promise))。 - `LOG_NON_ERROR` - 支持非错误控制台消息。（请参阅 [说明](#log-features)) - `LOG_ERROR` - 支持错误控制台消息（请参阅 [说明](#log-features)) 当没有明确选择功能时，`GREEDY` 被禁用，其他所有功能被启用。在 `gulp build` 命令上使用 `--enable GREEDY` 或从 `disableFeatures` 中移除它以恢复原始行为。如果您禁用任何功能，您还必须明确禁用 `GREEDY` 以获取 Promise 上的默认行为。 #### 贪婪 Promise 当启用 `GREEDY` 时，Prebid 会尽可能尝试控制主线程，使用 [自定义的 `Promise` 实现](https://github.com/prebid/Prebid.js/blob/master/libraries/greedy/greedyPromise.js)，该实现在 Promise 解决后不会将回调提交给调度程序（而是立即运行它们）。 禁用此行为指示 Prebid 使用标准的 `window.Promise`；这具有拆分任务执行的效果，使它们整体变慢，但给浏览器更多机会在中间运行其他任务，这可以改善 UX。 您还可以通过 `pbjs.Promise` 覆盖 Prebid 使用的 `Promise` 构造函数，例如： ``` var pbjs = pbjs || {}; pbjs.Promise = myCustomPromiseConstructor; ``` #### 日志记录 禁用 `LOG_NON_ERROR` 和 `LOG_ERROR` 会从源代码中移除大多数日志语句，这可以节省 bundle 大小。但请注意，禁用其中任何一个都没有测试覆盖。关闭它们需要您自担风险。 禁用日志记录 - 尤其是 `LOG_ERROR` - 也会使调试更加困难。考虑构建一个启用日志记录的单独版本用于调试目的。 我们建议仅在您能够通过测试框架确认真实世界的指标改进时才关闭日志记录的情况下运行构建。在没有此类框架的情况下使用此构建可能会导致性能意外变差。 ## 未压缩代码 您可以使用 `build-bundle-dev` 获取未压缩的代码版本用于调试： ``` gulp build-bundle-dev --modules=bidderA,module1,... ``` 结果将在 build/dev/prebid.js 中。 ## ES5 输出支持 为了与需要 ES5 语法的旧解析器或环境兼容，您可以使用 `--ES5` 标志生成 ES5 兼容的输出： ``` gulp build-bundle-dev --modules=bidderA,module1,... --ES5 ``` 这将： - 使用 CommonJS 模块将所有代码转译为 ES5 语法 - 目标浏览器：IE11+、Chrome 50+、Firefox 50+、Safari 10+ - 确保与旧版 JavaScript 解析器兼容 **注意**：没有 `--ES5` 标志时，构建默认将使用现代 ES6+ 语法以获得更好的性能和更小的 bundle 大小。 ## 本地测试 对代码进行 lint： ``` gulp lint ``` 进行 lint 并仅显示错误 ``` gulp lint --no-lint-warnings ``` 运行单元测试： ``` gulp test ``` 运行特定文件的单元测试（以 pubmaticBidAdapter_spec.js 为例）： ``` gulp test --file "test/spec/modules/pubmaticBidAdapter_spec.js" --nolint ``` 生成并查看代码覆盖率报告： ``` gulp test-coverage gulp view-coverage ``` 本地端到端测试可以通过以下方式完成： ``` gulp e2e-test --local ``` 对于有权访问 BrowserStack 的 Prebid.org 成员，可以通过以下方式完成额外的端到端测试： ``` gulp e2e-test --host=test.localhost ``` 要运行这些测试，需要以下项目： - 在您的 `hosts` 文件中设置 localhost 的别名（例如 `127.0.0.1 test.localhost`）；注意 - 您可以使用任何别名。在上面的命令行参数中使用此别名。 - 访问 [BrowserStack](https://www.browserstack.com/) 账户。在您的 bash_profile 中分配以下变量： ``` export BROWSERSTACK_USERNAME='YourUserNameHere' export BROWSERSTACK_ACCESS_KEY='YourAccessKeyHere' ``` 您可以从您的个人资料页面获取这些 BrowserStack 值。 用于开发： ``` (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); })(); ``` 用于部署： ``` (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); })(); ``` 在本地构建并运行项目： ``` gulp serve ``` 这将运行 `lint` 和 `test`，然后在 `http://localhost:9999` 启动一个从项目根目录提供服务的 Web 服务器。 导航到您的示例实现进行测试，如果您的 `prebid.js` 文件来自 `./build/dev` 目录，您将在浏览器的开发者工具中拥有可用的 sourcemap。 要运行示例文件，请转到： + `http://localhost:9999/integrationExamples/gpt/hello_world.html` 当您进行代码更改时，bundle 将自动重建，页面将自动重新加载。 ## 贡献 许多 SSP、bidder 和发布者为这个项目做出了贡献。[数百个 bidder](https://github.com/prebid/Prebid.js/tree/master/modules) 受到 Prebid.js 的支持。 有关指南，请参阅 [贡献](./CONTRIBUTING.md)。 我们的 PR 审核流程可以在 [这里](https://github.com/prebid/Prebid.js/tree/master/PR_REVIEW.md) 找到。 ### 添加 Bidder Adapter 要添加 bidder adapter 模块，请参阅 [如何添加 bidder adapter](https://docs.prebid.org/dev-docs/bidder-adaptor.html) 中的说明。 ### 代码质量 代码质量由 `.eslintrc` 定义，错误在终端中报告。 如果您贡献代码，您应该使用提供的 `.eslintrc` 设置 [配置您的编辑器](http://eslint.org/docs/user-guide/integrations#editors)。 ### 使用 Karma 进行单元测试 ``` $ gulp test --watch --browsers=chrome ``` 这将运行测试并保持 Karma 测试浏览器打开。如果您的 `prebid.js` 文件来自 `./build/dev` 目录，您在使用浏览器的开发者工具时也将拥有可用的 sourcemap。 + 要访问 Karma 调试页面，请转到 `http://localhost:9876/debug.html` + 测试结果请查看控制台 + 要在源代码中设置断点，请查看开发者工具 详细的代码覆盖率报告可以通过以下方式显式生成 ``` $ gulp test --coverage ``` 结果将在 ``` ./build/coverage ``` *注意*：从 2016 年 6 月开始，所有对 Prebid.js 的 pull request 都需要包含覆盖率大于 80% 的测试才能被合并。有关更多信息，请参阅 [#421](https://github.com/prebid/Prebid.js/issues/421)。 有关为 Prebid.js 编写测试的说明，请参阅 [测试 Prebid.js](https://prebid.org/dev-docs/testing-prebid.html)。 ### 支持的浏览器 Prebid.js 在 IE11 和 5.x 之前的现代浏览器上受支持。6.x+ 转译以目标 >0.25%；未淘汰；非 Opera Mini；非 IE11。 ### 治理 在 [这里](https://github.com/prebid/Prebid.js/tree/master/governance.md) 查看我们的治理模型。 ### 结束

标签：CMS安全, header bidding, JavaScript, MITM代理, npm, Prebid.js, RTB, SEO词, 代码贡献, 免费, 功能关键词, 动态加载模块, 响应拦截, 头部竞价, 威胁情报, 实时竞价, 广告SDK, 广告变现, 广告合作伙伴管理, 广告技术, 广告运营, 开发者工具, 技术栈, 数字营销, 数据可视化, 文档示例, 暗色界面, 模块化架构, 法律合规, 程序化广告, 自动化构建, 自定义脚本, 覆盖率状态