Documentation – Embed Privacy

This documentation is mainly limited to any development related content regarding Embed Privacy with some exceptions. Please use the support forums for general questions.

Regex pattern

The regex pattern, which can be set for any embed provider, defines a regular expression to match the content, which should be replaced by Embed Privacy’s overlay. For the default embed providers, it’s sufficient to only match a part of the URL.

If you want to add custom embed providers, the best way is to match the full element’s HTML tag as well:

Don’t use such regular expression

/sub\.example\.com/Code language: plaintext (plaintext)

Do use such regular expression

/<iframe src="(.*)sub\.example\.com([^"]*)"><\/frame>/Code language: plaintext (plaintext)

However, since version 1.6.0, any regex not containing a < and > will be extended with a variety of HTML tags to check for. So the regular expression /sub\.example\.com/ will become:

/<(blockquote|div|embed|iframe|object)([^"]*)"([^<]*)sub\.example\.com([^"]*)"([^>]*)(>(.*)<\/(blockquote|div|embed|iframe|object))?>/Code language: plaintext (plaintext)

You can filter the tags extending the regular expression with the filter embed_privacy_matcher_elements.

The beginning end ending / in the regex pattern are optional and automatically added in the code if not available.

Using Embed Privacy in a plugin

If you want to use Embed Privacy in a plugin for your custom code, the best way is to use the method Embed_Privacy::get_single_overlay() directly.

You can pass the content to search for replacements as well as the embed provider and additional arguments to match the full content or a part of it with an embed overlay.

Example

if ( class_exists( 'epiphyt\Embed_Privacy\Embed_Privacy' ) ) {
	$args = [
		'regex' => '/\custom\.example\.com/',
	];
	$content = '<p>Example Text</p><iframe src="https://custom.example.com"></iframe>';
	$content = epiphyt\Embed_Privacy\Embed_Privacy::get_instance()->get_single_overlay( $content, 'My Example', 'my-example', $args );
}
Code language: PHP (php)

See the method Embed_Privacy::get_single_overlay() for a full list of possible arguments.

Filters

embed_privacy_content

Through the filter embed_privacy_content the embed overlay content can be changed.

Parameters:
string $content The content
string $embed_provider The embed provider of this embed

Expects a string.

Through the filter embed_privacy_overlay_footer the footer of the embed overlay container can be changed.

Parameters:
string $footer_content The footer content

Expects a string.

embed_privacy_markup

Through the filter embed_privacy_markup the whole embed overlay container can be changed.

Parameters:
string $markup The markup
string $embed_provider The embed provider of this embed

Expects a string.

embed_privacy_has_embed since 1.3.0

Through the filter embed_privacy_has_embed the return value of Embed_Privacy::has_embed() can be overridden.

Parameters:
null $has_embed The default value

Expects anything other than null.

embed_privacy_assets_$embed_provider_lowercase since 1.4.5

Through the filter embed_privacy_assets_$embed_provider_lowercase additional assets that are necessary to get an embed working can be printed.

Each asset must be an array with at least a type parameter, which is either set to script for script elements or inline for an inline script.

If the type is set to script, the parameters handle and src are required, which are similar to identical parameters in wp_enqueue_script. Additionally, a parameter version can be added.

If the type is set to inline, the parameters data and object_name are required, which are similar to identical parameters in wp_add_inline_script.

Parameters:
array $assets List of embed assets
string $embed_provider_lowercase The current embed provider in lowercase

Expects an array with arrays.

embed_privacy_background_path_$embed_provider_lowercase since 1.1.0

Through the filter embed_privacy_background_path_$embed_provider_lowercase the path to the background image of the overlay can be changed.

Parameters:
string $background_path The default background path
string $embed_provider_lowercase The current embed provider in lowercase

Expects a string to a valid path to a background image.

embed_privacy_background_url_$embed_provider_lowercase since 1.1.0

Through the filter embed_privacy_background_url_$embed_provider_lowercase the URL to the background image of the overlay can be changed.

Parameters:
string $background_url The default background URL
string $embed_provider_lowercase The current embed provider in lowercase

Expects a string to a valid URL to a background image.

embed_privacy_logo_path_$embed_provider_lowercase

Through the filter embed_privacy_logo_path_$embed_provider_lowercase the path to the logo of the overlay can be changed.

Parameters:
string $logo_path The default logo path
string $embed_provider_lowercase The current embed provider in lowercase

Expects a string to a valid path to a logo.

embed_privacy_logo_url_$embed_provider_lowercase

Through the filter embed_privacy_logo_url_$embed_provider_lowercase the URL to the logo of the overlay can be changed.

Parameters:
string $logo_url The default logo URL
string $embed_provider_lowercase The current embed provider in lowercase

Expects a string to a valid URL to a logo.

embed_privacy_thumbnail_checked_orphaned since 1.7.0

The action embed_privacy_thumbnail_checked_orphaned fires after orphaned data for a provider have been checked and deleted, if applicable.

Parameters:
string $provider Provider name
string $id The ID of the embedded content
string $url The embed URL
bool $missin_id Whether the ID is missing
bool $missing_url Whether the URL is missing
string $meta_value The thumbnail filename
string $meta_key The thumbnail meta key
WP_Post $post The post object
int $post_id The post ID

embed_privacy_thumbnail_data_filename since 1.7.0

Through the filter embed_privacy_thumbnail_data_filename the thumbnail filename while getting thumbnail data can be changed.

Parameters:
string $thumbnail The thumbnail filename
WP_Post $post The post object
string $url The embed URL

Expects a string with a thumbnail filename.

embed_privacy_thumbnail_data_id since 1.7.0

Through the filter embed_privacy_thumbnail_data_id the thumbnail ID while getting thumbnail data can be changed.

Parameters:
string $id The thumbnail ID
WP_Post $post The post object
string $url The embed URL

Expects a string with a thumbnail ID.

embed_privacy_thumbnail_data_path since 1.7.0

Through the filter embed_privacy_thumbnail_data_path the thumbnail path while getting thumbnail data can be changed.

Parameters:
string $thumbnail The thumbnail path
WP_Post $post The post object
string $url The embed URL

Expects a string with a thumbnail path.

embed_privacy_thumbnail_data_url since 1.7.0

Through the filter embed_privacy_thumbnail_data_url the thumbnail URL while getting thumbnail data can be changed.

Parameters:
string $url The thumbnail URL
WP_Post $post The post object
string $url The embed URL

Expects a string with a thumbnail URL.

embed_privacy_thumbnail_get_from_provider since 1.7.0

The action embed_privacy_thumbnail_get_from_provider fires after thumbnail data have been processed.

Parameters:
string $return The returned oEmbed HTML
object $data A data object result from an oEmbed provider
string $url The URL of the content to be embedded

embed_privacy_thumbnail_path_$embed_provider_lowercase since 1.1.0

Through the filter embed_privacy_thumbnail_path_$embed_provider_lowercase the path to the thumbnail of the overlay can be changed.

Parameters:
string $thumbnail_path The default thumbnail path
string $embed_provider_lowercase The current embed provider in lowercase

Expects a string to a valid path to a thumbnail.

embed_privacy_thumbnail_supported_provider_names since 1.7.0

Through the filter embed_privacy_thumbnail_supported_provider_names the internal names of supported thumbnail providers can be changed.

Parameters:
array supported_providers Current supported provider names

Expects an array with thumbnail provider names.

embed_privacy_thumbnail_supported_providers since 1.7.0

Through the filter embed_privacy_thumbnail_supported_providers the titles of supported thumbnail providers can be changed.

Parameters:
array $supported_providers Current supported providers

Expects an array with localized thumbnail provider titles.

embed_privacy_thumbnail_url_$embed_provider_lowercase since 1.1.0

Through the filter embed_privacy_thumbnail_url_$embed_provider_lowercase the URL to the thumbnail of the overlay can be changed.

Parameters:
string $thumbnail_url The default thumbnail URL
string $embed_provider_lowercase The current embed provider in lowercase

Expects a string to a valid URL to a thumbnail.

embed_privacy_ignore_unknown_providers since 1.5.0

Through the filter embed_privacy_ignore_unknown_providers the processing of embeds of unknown embed providers can be disabled.

Parameters:
bool $ignore_unknown Whether unknown providers should be ignored
string $content The original content

Expects a boolean.

embed_privacy_ignored_shortcodes since 1.6.0

Through the filter embed_privacy_ignored_shortcodes shortcodes can be ignored from being replaced by an overlay.

Parameters:
string[] $ignored_shortcodes Current list of ignored shortcodes

Expects an array.

embed_privacy_matcher_elements since 1.6.0

Through the filter embed_privacy_matcher_elements the HTML elements, which will extend the regular expression for custom embed providers, can be changed.

Parameters:
array $allowed_tags The allowed tags
string $embed_provider_lowercase The current embed provider in lowercase

Expects an array.

embed_privacy_widget_output since 1.1.0

Through the filter embed_privacy_widget_output the output of a widget can be changed.

Parameters:
string $widget_output The widget’s output
string $widget_id The widget’s full ID
string $sidebar_id The current sidebar ID

Expects a string.

embed_privacy_opt_out_headline since 1.2.0

Through the filter embed_privacy_opt_out_headline the headline of the opt-out shortcode can be changed.

Parameters:
string $headline Current headline HTML
array $attributes Shortcode attributes

Expects a string.

embed_privacy_opt_out_subline since 1.2.0

Through the filter embed_privacy_opt_out_subline the sublime of the opt-out shortcode can be changed.

Parameters:
string $headline Current subline HTML
array $attributes Shortcode attributes

Expects a string.

embed_privacy_editor_fields

Through the filter embed_privacy_editor_fields additional fields can be rendered in the embed provider editor screen.

Parameters:
int $post_id The current post ID

Expects a string.

embed_privacy_register_fields since 1.2.0

Through the filter embed_privacy_register_fields additional fields can be registered.

Parameters:
int $post_id The current post ID

Expects an array.

embed_privacy_fields

Through the filter embed_privacy_fields all registered fields can be changed.

Parameters:
array $fields Registered fields

Expects an array.

embed_privacy_valid_files

Through the filter embed_privacy_valid_files the name of valid files in POST requests of the editor can be changed.

Parameters:
array The default name list

Expects an array.

jetpack_sharing_facebook_app_id since 1.4.5

Through the filter jetpack_sharing_facebook_app_id the Facebook app ID of Jetpack sharing can be changed.

Parameters:
string $app_id The current app ID

Expects a string.

Table of contents

  1. Regex pattern
  2. Using Embed Privacy in a plugin
  3. Filters