Ticket #43473: PRIVACY-POLICY-CONTENT-HOOK.md

# How to Connect Your Plugin to Core's New Privacy Policy Content View

## Background

In WordPress 4.9.x, new tools were added to make compliance easier with laws
like the European Union's General Data Protection Regulation, or GDPR for
short. Among the tools added is a means to create or designate a page
on your site as a Privacy Policy page.

In addition to being able to create or designate such a page, when you
edit that page, a meta box will display suggested contributions to your
site's privacy policy from WordPress and participating plugins.

Each plugin's contributions includes a Copy button to make it easy to
copy the text into the clipboard for pasting by the administrator into
and appropriate spot in the site's privacy policy.

## How It Works

Plugins can hook translated text using a new function,
`wp_add_privacy_policy_content`, to inform administrators of how the plugin
collects, accesses, retains and/or shares personal data and/or how it
tracks users and visitors to the site.

## How To Phrase Your Plugin's Contributions

To minimize the amount of editing administrators need to do, it is best
to phrase your plugin's contributions as if they are appearing on the site's
privacy policy and being read by the end user (i.e. not the admin.)

For example:

'When you leave a comment on this site, we send your name, email address,
IP address and comment text to the example.com spam detection service
to prevent spam from appearing on this site. Example.com does not
retain your personal data.'

## What to Do

A plugin should call `wp_add_privacy_policy_content` in the context of an
`admin_init` hook, e.g.:

```
function my_plugin_privacy_declarations() {
        if ( function_exists( 'wp_add_privacy_policy_content' ) ) {

                $content = sprintf(
                        __( 'When you leave a comment on this site, we send your name, email
                                address, IP address and comment text to the example.com spam detection
                                service to prevent spam from appearing on this site. Example.com does
                                not retain your personal data.

                                The example.com privacy policy is <a href="%s">here</a>.',
                                'my_plugin_textdomain' ),
                        'https://example.com/'
                );

                wp_add_privacy_policy_content(
                        'My Plugin Name',
                        wp_kses_post( wpautop( $content ) )
                );
        }
}

add_action( 'admin_init', 'my_plugin_privacy_declarations' );
```

The next thing the plugin needs to do is to register the callback by
filtering the eraser array using the `wp_privacy_personal_data_erasers`
filter.

When registering you provide a friendly name for the eraser (to aid in
debugging - this friendly name is not shown to anyone at this time)
and the callback, e.g.

```
function register_my_plugin_eraser( $erasers ) {
  $erasers[] = array(
    'eraser_friendly_name' => __( 'Comment Location Plugin' ),
    'callback'             => 'my_plugin_eraser',
    );
  return $erasers;
}

add_filter(
  'wp_privacy_personal_data_erasers',
  'register_my_plugin_eraser',
  10
);
```

And that's all there is to it! Your plugin will now clean up its personal
data!