API

pytracking

pytracking.get_click_tracking_result(encoded_url_path: str, request_data: Dict = None, configuration: Configuration = None, **kwargs) → TrackingResult[source]

Get a TrackingResult instance from an encoded click tracking link.

Parameters:

encoded_url_path – The part of the URL that is encoded and contains the tracking information or the full URL (base_click_tracking_url must be provided)
request_data – The dictionary to attach to the TrackingResult representing the information (e.g., user agent) of the client that requested the tracking link.
configuration – An optional Configuration instance.
kwargs – Optional configuration parameters. If provided with a Configuration instance, the kwargs parameters will override the Configuration parameters.

pytracking.get_click_tracking_url(url_to_track: str, metadata: Dict = None, configuration: Configuration = None, **kwargs) → str[source]

Returns a tracking URL encoding the link to track, the provided metadata, and other information specified in the configuration or kwargs.

Parameters:

url_to_track – The URL to track.
metadata – A dict that can be json-encoded and that will be encoded in the tracking link.
configuration – An optional Configuration instance.
kwargs – Optional configuration parameters. If provided with a Configuration instance, the kwargs parameters will override the Configuration parameters.

pytracking.get_click_tracking_url_path(url: str, configuration: Configuration = None, **kwargs) → str[source]

Get a part of a URL that contains the encoded click tracking information. This is the part that needs to be supplied to get_click_tracking_result.

Parameters:

url – The full tracking URL
configuration – An optional Configuration instance.
kwargs – Optional configuration parameters. If provided with a Configuration instance, the kwargs parameters will override the Configuration parameters.

pytracking.get_open_tracking_pixel()[source]: Returns a tuple consisting of a binary string (the transparent PNG pixel) and the MIME type.

pytracking.get_open_tracking_result(encoded_url_path: str, request_data: Dict = None, configuration: Configuration = None, **kwargs) → TrackingResult[source]

Get a TrackingResult instance from an encoded open tracking link.

Parameters:

encoded_url_path – The part of the URL that is encoded and contains the tracking information or the full URL (base_open_tracking_url must be provided)
request_data – The dictionary to attach to the TrackingResult representing the information (e.g., user agent) of the client that requested the tracking link.
configuration – An optional Configuration instance.
kwargs – Optional configuration parameters. If provided with a Configuration instance, the kwargs parameters will override the Configuration parameters.

pytracking.get_open_tracking_url(metadata: Dict = None, configuration: Configuration = None, **kwargs) → str[source]

Returns a tracking URL encoding the metadata and other information specified in the configuration or kwargs.

Parameters:

metadata – A dict that can be json-encoded and that will be encoded in the tracking link.
configuration – An optional Configuration instance.
kwargs – Optional configuration parameters. If provided with a Configuration instance, the kwargs parameters will override the Configuration parameters.

pytracking.get_open_tracking_url_path(url: str, configuration: Configuration = None, **kwargs) → str[source]

Get a part of a URL that contains the encoded open tracking information. This is the part that needs to be supplied to get_open_tracking_result.

Parameters:

url – The full tracking URL
configuration – An optional Configuration instance.
kwargs – Optional configuration parameters. If provided with a Configuration instance, the kwargs parameters will override the Configuration parameters.

pytracking.html

pytracking.html.adapt_html(html_text: str, extra_metadata: dict, click_tracking: bool = True, open_tracking: bool = True, configuration: Configuration = None, **kwargs) → str[source]

Modify HTML by adding tracking links and a tracking pixel.

Parameters:

html_text (str) – The HTML content to modify.
extra_metadata (dict) – Additional data to include in tracking links.
click_tracking (bool) – If True, replace links with tracking links.
open_tracking (bool) – If True, add a tracking pixel.
configuration (Configuration) – Custom configuration settings.
**kwargs – Additional configuration parameters.

Returns:

Modified HTML content with tracking elements.

Return type:

str

This function processes the input HTML to add tracking capabilities:

Replaces regular links with click-tracking links if click_tracking is True.
Adds a 1x1 transparent pixel for open tracking if open_tracking is True.
Uses the provided configuration or creates a new one from kwargs.

pytracking.webhook

pytracking.webhook.send_webhook(tracking_result: TrackingResult, configuration: Configuration = None, **kwargs)[source]

Sends a POST request to the webhook URL specified in tracking_result.

The POST request will have a body of type application/json that contains a json representation of the tracking result:

{
    "is_open_tracking": False,
    "is_click_tracking": True,
    "metadata": {...},
    "request_data": None,
    "tracked_url": "http://...",
    "timestamp": 1389177318
}

Parameters:

tracking_result – The TrackingResult instance to post to a webhook.
configuration – An optional Configuration instance.
kwargs – Optional configuration parameters. If provided with a Configuration instance, the kwargs parameters will override the Configuration parameters.

pytracking.django

class pytracking.django.ClickTrackingView(**kwargs)[source]: Constructor. Called in the URLconf; can contain helpful extra keyword arguments, and other things.

class pytracking.django.OpenTrackingView(**kwargs)[source]: Constructor. Called in the URLconf; can contain helpful extra keyword arguments, and other things.

class pytracking.django.TrackingView(**kwargs)[source]

Constructor. Called in the URLconf; can contain helpful extra keyword arguments, and other things.

get_configuration() → Configuration[source]

Returns a Configuration instance built from settings.PYTRACKING_CONFIGURATION.

Override this method if you want to build your own Configuration instance.

notify_decoding_error(exception: Exception, request: HttpRequest)[source]

Called when a decoding error occurs, and before responding with a 404.

Parameters:: exception – The exception that was raised when trying to decode a tracking link.

notify_tracking_event(tracking_result: TrackingResult)[source]

Called once the tracking link has been decoded, and before responding with a redirect or a tracking pixel.

Parameters:: tracking_result – An instance of TrackingResult.

pytracking.django.get_configuration_from_settings(settings_name='PYTRACKING_CONFIGURATION')[source]: Builds a Configuration instance from the parameters in settings.PYTRACKING_CONFIGURATION.

pytracking.django.get_request_data(request: HttpRequest) → Dict[str, str][source]

Retrieves the user agent and the ip of the client from the Django request.

We use ipware to retrieve the “real” IP (e.g., load balancer will often put the client IP in X-Forwarded-For header).

pytracking.django.get_tracking_result(request: HttpRequest, path: str, is_open: bool, configuration: Configuration = None, **kwargs) → TrackingResult[source]

Builds a tracking result from a Django request.

Parameters:

request – A Django request
path – The path of the URL that is encoded (usually possible to distinguish this path using a URL parameter).
is_open – If this is an open tracking link request.
configuration – An optional Configuration instance.
kwargs – Optional configuration parameters. If provided with a Configuration instance, the kwargs parameters will override the Configuration parameters.