Media Download Module

This module provides functionality for media content download using Selenium, given ads data urls and a valid access token.

find_media_element Function

AdDownloader.media_download.find_media_element(driver, xpaths)[source]

Try a list of candidate xpaths in order and return the first matching element.

Parameters:

driver (webdriver.Chrome) – A running Chrome webdriver, already navigated to the target page.
xpaths (list[str]) – Candidate xpaths to try, in order.

Returns:

The first matching WebElement, or None if none of the xpaths matched.

Return type:

WebElement | None

Example:

>>> img_element = find_media_element(driver, IMG_XPATHS)

find_fallback_media Function

AdDownloader.media_download.find_fallback_media(driver, min_dimension=100)[source]

Structure-agnostic fallback for when none of the known positional xpaths above matched: instead of guessing another exact div path, look for any <img>/<video> anywhere inside #content that’s at least min_dimension px on each side (filtering out small icons like the page avatar). This costs one query total (a single execute_script call) and, unlike the xpath lists, keeps working across page redesigns without needing a manual update - it’s only used as a last resort, so it adds no overhead for ads that already match a known xpath.

Parameters:

driver (webdriver.Chrome) – A running Chrome webdriver, already navigated to the target page.
min_dimension (int) – Minimum width/height (px) for an element to count as real media rather than an icon/avatar.

Returns:

A tuple (images, video). images is a list of {‘src’, ‘width’, ‘height’} dicts for every large enough <img> found, largest first (empty if none). video is the largest matching <video> dict, or None.

Return type:

tuple(list[dict], dict | None)

Example:

>>> images, video = find_fallback_media(driver)

detect_removed_ad Function

AdDownloader.media_download.detect_removed_ad(driver)[source]

Check whether the current ad snapshot page indicates the ad creative was removed by Meta for not following advertising policies (as opposed to the ad simply being text-only).

Parameters:: driver (webdriver.Chrome) – A running Chrome webdriver, already navigated to the target page.
Returns:: True if a known “removed” message was found on the page.
Return type:: bool

Example:

>>> if detect_removed_ad(driver):
...     print("Ad media was removed by Meta for a policy violation.")

download_media Function

AdDownloader.media_download.download_media(media_url, media_type, ad_id, media_folder)[source]

Download media content for an ad given its ID.

Parameters:

media_url (str) – The url address for accessing the media content.
media_type (str) – The type of the media content to download, can be ‘image’ or ‘video’.
ad_id (str) – The ID of the ad for which media content is downloaded.
media_folder (str) – The path to the folder where media content will be saved.

Example:

>>> driver.get(data['ad_snapshot_url'][0])
>>> img_element = find_media_element(driver, IMG_XPATHS)
>>> media_url = img_element.get_attribute('src')
>>> media_type = 'image'
>>> download_media(media_url, media_type, str(data['id'][i]), folder_path_img)

accept_cookies Function

AdDownloader.media_download.accept_cookies(driver)[source]

Accept the cookies in a running Chrome webdriver. Only needs to be done once, when openning the webdriver.

Parameters:: driver (webdriver.Chrome) – A running Chrome webdriver.

Example:

>>> driver = webdriver.Chrome()
>>> driver.get(data['ad_snapshot_url'][0]) # start from here to accept cookies
>>> accept_cookies(driver)

start_media_download Function

AdDownloader.media_download.start_media_download(project_name, nr_ads, data=None, random_state=None)[source]

Start media content download for a given project and desired number of ads. The ads media are saved in the output folder with the project_name.

Parameters:

project_name (str) – The name of the current project.
nr_ads (int) – The desired number of ads for which media content should be downloaded.
data (pandas.DataFrame) – A dataframe containing an ad_snapshot_url column.
random_state (int, optional) – Seed used to sample nr_ads ads out of data, for reproducibility. Default is None, in which case a seed is generated automatically and printed/logged so the exact same sample of ads can be reproduced later by passing it back in.

Example:

>>> start_media_download(project_name = "test1", nr_ads = 20, data = data)
>>> # for a reproducible sample, pass a seed - if omitted, one is generated and reported
>>> start_media_download(project_name = "test1", nr_ads = 20, data = data, random_state = 42)

extract_frames Function

AdDownloader.media_download.extract_frames(video, project_name, interval=None, num_frames=None)[source]

Extract a number of frames from ad videos

Parameters:

video (str) – The name of the video for which frames should be extracted.
project_name (str) – The name of the current project.
interval (int) – The interval between the (in seconds), optional. Should be specified instead of num_frames.
num_frames (int) – The number of frames to extract, distributed evenly, optional. Should be specified instead of the interval.

Example:

>>> extract_frames(video = "test_video.mp4", project_name = "test1", interval = 3)