README

Air cookie提供简单的cookie横幅和管理。

使用CookieConsentjavascript插件作为基础，使得其在WordPress中的使用更加简便。

特性

简单轻量级的cookie横幅
在同意cookies之前阻止第三方嵌入
在同意cookies后轻松加载脚本和执行自定义javascript
支持多种不同的cookie类别
支持Polylang的多语言网站
访客同意记录
cookie类别修订控制

使用方法

链接到cookie设置

记得在页脚中添加链接，这样就可以随时打开cookie设置！

<a href="#" data-cc="c-settings" class="cc-link">Cookie settings</a>

如果您已安装并启用了Polylang，请使用

<a href="#" data-cc="c-settings" class="cc-link">
  <?php echo pll_translate_string( 'Evästeasetukset', pll_current_language() ); ?>
</a>

Cookie类别

默认情况下，插件有两个cookie类别 necessary、functional和analytics。您可以使用air_cookie\categories过滤器添加新类别，如下所示。

add_filter( 'air_cookie\categories', 'my_add_cookie_category' );
function my_add_cookie_category( $categories ) {
  $categories[] = [
    'key'         => 'ads',
    'enabled'     => false, // it is advised to have categories disabled by default
    'readonly'    => false, // user should have always control over categories
    'title'       => 'Ads',
    'description' => 'This site uses external services to display ads, and they might set some cookies.',
  ];

  return $categories;
}

当添加新类别时，该函数本身负责处理标题和描述的翻译。

还有一个air_cookie\categories\{category-key}过滤器，可以更改单个类别的设置。

在同意cookies后加载脚本

加载外部脚本的简单方法是将script标签更改为

<script type="text/plain" data-src="<uri-to-script>" data-cookiecategory="analytics" defer>

上面的示例仅适用于不需要在脚本加载后执行任何额外javascript的脚本。如果需要执行额外的javascript，请使用下面的示例。

add_action( 'air_cookie_js_analytics', 'my_add_js_for_analytics' );
function my_add_js_for_analytics() {
  ob_start(); ?>
    cc.loadScript( 'https://#/analytics.js', function() {
      ga('create', 'UA-XXXXXXXX-Y', 'auto');  //replace UA-XXXXXXXX-Y with your tracking code
      ga('send', 'pageview');
    } );
  <?php echo ob_get_clean();
}

Google Tag Manager (gtm.js)

add_action( 'air_cookie_js_analytics', 'my_add_js_for_analytics' );
function my_add_js_for_analytics() {
  ob_start(); ?>
    (function (w, d, s, l, i) {
      w[l] = w[l] || [];
      w[l].push({ "gtm.start": new Date().getTime(), event: "gtm.js" });
      var f = d.getElementsByTagName(s)[0],
        j = d.createElement(s),
        dl = l != "dataLayer" ? "&l=" + l : "";
      j.async = true;
      j.src = "https://#/gtm.js?id=" + i + dl;
      f.parentNode.insertBefore(j, f);
    })(window, document, "script", "dataLayer", "GTM-XXXXXX");
  <?php echo ob_get_clean();
}

Google Tag Manager (gtag.js)

add_action( 'air_cookie_js_analytics', 'my_add_js_for_analytics' );
function my_add_js_for_analytics() {
  ob_start(); ?>
    cc.loadScript( 'https://#/gtag/js?id=UA-XXXXXXXXX-X', function() {
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-XXXXXXXXX-X');
    });
  <?php echo ob_get_clean();
}

Google Analytics (analytics.js)

add_action( 'air_cookie_js_analytics', 'my_add_js_for_analytics' );
function my_add_js_for_analytics() {
  ob_start(); ?>
    cc.loadScript( 'https://#/analytics.js', function() {
      ga('create', 'UA-XXXXXXXX-Y', 'auto');  //replace UA-XXXXXXXX-Y with your tracking code
      ga('send', 'pageview');
    } );
  <?php echo ob_get_clean();
}

将插件javascript移动到同意cookies后加载

// Disable script by nulling the tag on latest possible chance
add_filter( 'script_loader_tag', function( $tag, $handle ) {
  if ( 'our-script-handle' === $handle ) {
    return '';
  }

  return $tag;
}, 10, 2 );

// Load stamped.io script on air cookie
add_action( 'air_cookie_js_functional', function() {
  $stampedio_url = get_script_src_by_handle( 'our-script-handle' );
  if ( empty( $stampedio_url ) ) {
    return;
  }

  ob_start(); ?>
    cc.loadScript( '<?php echo esc_url( $stampedio_url ) ?>' );
  <?php echo ob_get_clean(); // phpcs:ignore
} ); // end woocommerce_ga_integration_script_for_air_cookie

function get_script_src_by_handle( $handle ) {
  global $wp_scripts;
  if ( in_array( $handle, $wp_scripts->queue ) ) {
    return $wp_scripts->registered[ $handle ]->src;
  }
} // end get_script_src_by_handle

// Disable stamped.io script by nulling the tag on latest possible chance
add_filter( 'script_loader_tag', function( $tag, $handle ) {
  if ( 'woo-stamped-io-public-custom' === $handle ) {
    return '';
  }

  return $tag;
}, 10, 2 );

// Load stamped.io script on air cookie
add_action( 'air_cookie_js_functional', __NAMESPACE__ . '\woocommerce_stampedio_script_for_air_cookie' );
function woocommerce_stampedio_script_for_air_cookie() {
  $stampedio_url = get_script_src_by_handle( 'woo-stamped-io-public-custom' );
  if ( empty( $stampedio_url ) ) {
    return;
  }

  ob_start(); ?>
    cc.loadScript( '<?php echo esc_url( $stampedio_url ) ?>' );
  <?php echo ob_get_clean(); // phpcs:ignore
} // end woocommerce_ga_integration_script_for_air_cookie

在同意cookies后执行自定义javascript

在同意某些cookie类别后，您可以执行自己的javascript。有两种方法可以实现这一点：将javascript直接添加到header中或使用自定义javascript事件。

直接添加javascript

每个cookie类别都有自己的操作，其中可以输出javascript以添加到主header脚本标签中。

add_action( 'air_cookie_js_<category-key>', 'my_add_js_for_<category-key>' );
function my_add_js_for_<category-key>() {
  ob_start(); ?>
    console.log( 'Hello world!' );
  <?php echo ob_get_clean();
}

如果您希望使用自己的script标签，可以使用以下示例

<script type="text/plain" data-cookiecategory="<category-key>">
  console.log( 'Hello world!' );
</script>

单独的javascript文件

如果您有需要在某些类别被接受后才执行代码的自定义javascript文件，有自定义javascript事件可供使用。

每个cookie类别都有自己的事件，您可以将事件监听器绑定到其中。

document.addEventListener( 'air_cookie_<category-key>', (event) => {
  console.log( 'Hello world!' );
} );

还有一个全局自定义事件可供使用，其中将类别键作为detail传递。

document.addEventListener( 'air_cookie', (event) => {
  console.log( 'Hello world! The category is ' + event.detail.category );
} );

更改设置

设置名称遵循CookieConsents选项名称。一些设置的默认值设置与CookieConsent的默认值不同

您可以使用air_cookie\settings过滤器更改设置，该过滤器包含所有设置，或者使用air_cookie\settings\{setting-name}过滤器更改单个设置。

add_filter( 'air_cookie\settings', 'my_modify_cc_settings' );
function my_modify_cc_settings( $settings ) {
  $settings['page_scripts'] = false;
  return $settings;
}

add_filter( 'air_cookie\settings\page_scripts', 'my_modify_cc_setting_page_scripts' );
function my_modify_cc_setting_page_scripts( $setting ) {
  return false;
}

请注意，这些过滤器不包含字符串或cookie类别。air_cookie\settings_all过滤器包含所有内容，但强烈不建议使用，因为每个内容都有其特定的过滤器。

修改默认字符串

如果需要修改默认字符串，最推荐的修改方式是通过Polylang字符串翻译。要更改所有语言的字符串，不需要修改源代码。

如果未使用Polylang，存在一个air_cookie\strings过滤器，其中包含所有字符串，以及针对单个字符串的air_cookie\strings\{string-key}过滤器。

add_filter( 'air_cookie\strings', 'my_modify_cc_strings' );
function my_modify_cc_strings( $strings ) {
  $strings['consent_modal_title'] = 'Have a cookie?';
  return $strings;
}

add_filter( 'air_cookie\strings\consent_modal_title', 'my_modify_cc_string_consent_modal_title' );
function my_modify_cc_string_consent_modal_title( $string ) {
  return 'Have a cookie?';
}

第三方嵌入阻止

默认情况下，第三方嵌入阻止是激活的，以下服务的所有嵌入都被阻止：YouTube、Vimeo、Instagram、Facebook、Twitter、Soundcloud、Spotify、Slideshare、WordPress.com视频、Embedly、Issuu、Imgur和TikTok。

通过air_cookie\embeds过滤器返回false来禁用此功能。

add_filter( 'air_cookie\embeds', '__return_false' );

将iframe嵌入替换为占位符，让访客知道嵌入可能会使用跟踪cookie。然后他们有机会允许所有cookie或启用单个嵌入一次。

对于脚本嵌入，我们只需将src标签替换为data-src，并添加data-cookiecategory，使其能够以CookieConsents的方式加载脚本。

嵌入的cookie类别

当此功能启用时，会添加一个新的cookie类别。当此类别被接受时，所有嵌入都会加载并显示。

使用字符串过滤器air_cookie\strings修改此类别的文本。

占位符的缩略图

Iframe嵌入占位符支持缩略图。如果没有缩略图，iframe将被替换为黑色背景框。YouTube和Vimeo嵌入会自动获得占位符。

对于其他服务，您可以使用如下所示的air_cookie\embeds\thumbnail过滤器。

add_filter( 'air_cookie\embeds\thumbnail', 'my_maybe_add_thumbnail', 10, 2 );
function my_maybe_add_thumbnail( $thumbnail, $src ) {
  // If thumbnail is already set, bail.
  if ( ! empty( $thumbnail ) ) {
    return $thumbnail;
  }

  // Do your magic to get the thumbnail

  return 'https://your.thumbna.il/location.jpg';
}

Vimeo和Do Not Track

Vimeo嵌入的处理方式略有不同。对于这些嵌入，我们不会添加占位符或阻止它们。相反，我们在嵌入的src中添加Do Not Track参数，禁用所有Vimeo跟踪和统计。

使用air_cookie\embeds\vimeo\add_dnt过滤器禁用此功能，但请注意，WordPress核心默认也会添加dnt。

如果您希望在Vimeo嵌入启用Do Not Track的情况下仍然显示占位符，请使用air_cookie\embeds\vimeo\skip_dnt过滤器。

修订控制

Cookie策略修订号会自动根据cookie类别的key、enabled和readonly值计算。如果添加了新的类别，某些类别被删除或值发生变化，则会再次显示同意模态框。

如果您希望手动控制修订号，请使用air_cookie\categories\revision过滤器。第一个参数是计算出的修订号，第二个参数是包含所有当前cookie类别的数组。

访客同意记录

芬兰的cookie法规要求网站所有者能够指明特定访客何时接受cookie。这就是为什么插件有简单的访客同意记录系统。

每个访客都会被赋予唯一的uuid4 ID。当访客接受任何cookie类别时，他们的浏览器将向REST API发送一个小请求，记录他们的ID、当前修订号、接受的cookie类别、事件的时间戳和过期时间戳。这些数据存储在自定义数据库表中，不包含任何有关访客的额外信息。

目前没有禁用此功能的方法。

安装

下载最新版本（下载链接）作为一个zip包，并将其解压缩到您的插件目录中。

或者使用composer安装，在项目目录中运行命令composer require digitoimistodude/air-cookie，或者在您的composer.json文件中添加"digitoimistodude/air-cookie":"dev-master"。

更新

当发布新版本时，更新将自动分发。

变更日志

变更日志可以从发布页面找到。

贡献

如果您对插件有任何想法或发现任何问题，请告诉我们。在贡献想法或报告关于“缺失”的功能或与此问题性质相关的事项之前，请注意，此插件是为了满足我们的客户需求而制定的，可能不会朝着您期望的方向发展。非常感谢。

digitoimistodude / air-cookie

维护者

详细信息