pytracking 0.2.2

1. 在邮件中添加追踪信息

要跟踪电子邮件的打开情况，普遍接受的策略是在电子邮件末尾添加一个小的 1x1 透明像素。当用户打开电子邮件时，电子邮件客户端（例如，gmail、outlook、thunderbird）将通过发出 GET 请求来加载像素。然后，服务请求的 Web 服务器将记录打开并通知电子邮件的发件人。

要跟踪链接点击，普遍接受的策略是重写电子邮件中的链接以将目的地更改为代理。一旦用户点击链接，代理将用户重定向到真实链接并通知发件人电子邮件。

pytracking 提供了一种无状态策略来打开和点击跟踪：您要跟踪的所有信息都编码在像素（打开）和代理（点击）URL 中。例如，如果您想跟踪与特定电子邮件关联的客户 ID 和交易 ID，pytracking 将在 URL 中编码此信息。当用户打开电子邮件或单击链接时，客户 ID 和交易 ID 将被解码，然后可以发送到 Webhook。

有关快速示例，请参阅获取打开的跟踪链接部分。

2. 处理电子邮件打开和链接点击

一旦用户打开电子邮件或单击链接，电子邮件客户端就会向编码的 URL 发送请求。您的 Web 服务器将收到此类请求并将其传递给 pytracking，后者将对跟踪信息进行解码。然后，您可以直接使用跟踪信息（例如，更新您的跟踪数据库），也可以将信息发送到 webhook。

在链接跟踪的情况下，解码信息将包含您必须将电子邮件客户端重定向到的原始 URL。

有关快速示例，请参阅从 URL 获取打开的跟踪数据部分。

pytracking 提供的可选主要功能

1. 加密：pytracking 使用 base 64 对您的跟踪信息进行编码，任何人都可以对其进行解码。您可以选择加密您的跟踪信息，只有在您拥有密钥的情况下才能对其进行解码。有关详细信息，请参阅 加密数据部分。

2. HTML 修改：pytracking 可以修改 HTML 电子邮件以替换所有链接并添加跟踪像素。请参阅修改 HTML 电子邮件以添加跟踪链接部分。

3. Django：如果你使用 Django 来提供打开和点击跟踪 URL，你可以扩展 pytracking Django 视图，它已经提供了重定向和像素服务。请参阅将pytracking 与 Django 一起使用部分。

4. Webhook：pytracking 提供了一个快捷功能来向 webhook 发出 POST 请求。请参阅通知 Webhook部分。

编码

您可以对这两种链接中的元数据进行编码。例如，您可以将客户 ID 与点击跟踪链接相关联，这样当客户点击该链接时，您就可以确切地知道是哪个客户点击了该链接。

pylinktracking 实现了一种无状态的跟踪策略：所有必要的信息都可以编码在跟踪链接中。您可以选择将通用设置（例如，与所有链接关联的默认元数据、webhook URL）保留在单独的配置中。

该信息使用 url-safe base64 编码，因此任何拦截您的链接的人，包括您的客户，都可能解码该信息。您可以选择加密跟踪信息（见下文）。

大多数函数将pytracking.Configuration实例作为参数，该 实例告诉如何生成链接。您还可以将配置参数作为**kwargs参数传递，或者可以混合使用两者：kwargs 将覆盖配置参数。

解码

一旦您从跟踪链接获得请求，您可以使用 pytracking 对链接进行解码并获取pytracking.TrackingResult实例，其中包含要重定向到的链接（如果是点击跟踪链接）、相关元数据、要通知的 webhook URL 等。

获取开放跟踪链接

import pytracking

open_tracking_url = pytracking.get_open_tracking_url(
    {"customer_id": 1}, base_open_tracking_url="https://trackingdomain.com/path/",
    webhook_url="http://requestb.in/123", include_webhook_url=True)

# This will produce a URL such as:
# https://trackingdomain.com/path/e30203jhd9239754jh21387293jhf989sda=

使用配置获取打开的跟踪链接

import pytracking

configuration = pytracking.Configuration(
    base_open_tracking_url="https://trackingdomain.com/path/",
    webhook_url="http://requestb.in/123",
    include_webhook_url=False)

open_tracking_url = pytracking.get_open_tracking_url(
    {"customer_id": 1}, configuration=configuration)

# This will produce a URL such as:
# https://trackingdomain.com/path/e30203jhd9239754jh21387293jhf989sda=

获取点击跟踪链接

import pytracking

click_tracking_url = pytracking.get_click_tracking_url(
    "http://www.example.com/?query=value", {"customer_id": 1},
    base_click_tracking_url="https://trackingdomain.com/path/",
    webhook_url="http://requestb.in/123", include_webhook_url=True)

# This will produce a URL such as:
# https://trackingdomain.com/path/e30203jhd9239754jh21387293jhf989sda=

从 URL 获取打开的跟踪数据

import pytracking

full_url = "https://trackingdomain.com/path/e30203jhd9239754jh21387293jhf989sda="
tracking_result = pytracking.get_open_tracking_result(
    full_url, base_open_tracking_url="https://trackingdomain.com/path/")

# Metadata is in tracking_result.metadata
# Webhook URL is in tracking_result.webhook_url

从 URL 获取点击跟踪数据

import pytracking

full_url = "https://trackingdomain.com/path/e30203jhd9239754jh21387293jhf989sda="
tracking_result = pytracking.get_click_tracking_result(
    full_url, base_click_tracking_url="https://trackingdomain.com/path/")

# Metadata is in tracking_result.metadata
# Webhook URL is in tracking_result.webhook_url
# Tracked URL to redirect to is in tracking_result.tracked_url

获取 1x1 透明 PNG 像素

import pytracking

(pixel_byte_string, mime_type) = pytracking.get_open_tracking_pixel()

Django 设置中的配置参数

您可以通过在设置文件中添加此键来在 Django 设置中提供默认配置参数：

PYTRACKING_CONFIGURATION = {
    "webhook_url": "http://requestb.in/123",
    "base_open_tracking_url": "http://tracking.domain.com/open/",
    "base_click_tracking_url": "http://tracking.domain.com/click/",
    "default_metadata": {"analytics_key": "123456"},
    "append_slash": True
}

扩展默认视图

from pytracking import Configuration
from pytracking.django import OpenTrackingView, ClickTrackingView

class MyOpenTrackingView(OpenTrackingView):

    def notify_tracking_event(self, tracking_result):
        # Override this method to do something with the tracking result.
        # tracking_result.request_data["user_agent"] and
        # tracking_result.request_data["user_ip"] contains the user agent
        # and ip of the client.
        send_tracking_result_to_queue(tracking_result)

    def notify_decoding_error(self, exception, request):
        # Called when the tracking link cannot be decoded
        # Override this to, for example, log the exception
        logger.log(exception)

    def get_configuration(self):
        # By defaut, fetchs the configuration parameters from the Django
        # settings. You can return your own Configuration object here if
        # you do not want to use Django settings.
        return Configuration()


class MyClickTrackingView(ClickTrackingView):

    def notify_tracking_event(self, tracking_result):
        # Override this method to do something with the tracking result.
        # tracking_result.request_data["user_agent"] and
        # tracking_result.request_data["user_ip"] contains the user agent
        # and ip of the client.
        send_tracking_result_to_queue(tracking_result)

    def notify_decoding_error(self, exception, request):
        # Called when the tracking link cannot be decoded
        # Override this to, for example, log the exception
        logger.log(exception)

    def get_configuration(self):
        # By defaut, fetchs the configuration parameters from the Django
        # settings. You can return your own Configuration object here if
        # you do not want to use Django settings.
        return Configuration()

网址配置

将此添加到您的 urls.py 文件中：

urlpatterns = [
    url(
        "^open/(?P<path>[\w=-]+)/$", MyOpenTrackingView.as_view(),
        name="open_tracking"),
    url(
        "^click/(?P<path>[\w=-]+)/$", MyClickTrackingView.as_view(),
        name="click_tracking"),
]