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

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

Do

/<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

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

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

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

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_path_$embed_provider_lowercase

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_url_$embed_provider_lowercase

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

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

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

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

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

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

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

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

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.