Microsoft Advertising Conversions API: integracja server-side UET

Microsoft Advertising Conversions API (CAPI) zapewnia serwerową drogę przesyłania zdarzeń z procesu zakupowego, CRM i innych systemów. Pozwala to ograniczyć luki spowodowane brakiem żądania z przeglądarki. Przyjęte zdarzenie nie jest jednak automatycznie przypisaną konwersją: nadal obowiązują zgody, identyfikatory, cele konwersji i reguły atrybucji.

Wdrożenie obejmuje mapowanie zdarzeń, dane dostępowe, dozwolone identyfikatory, obsługę duplikatów i monitorowaną kolejkę wysyłki. Uniwersalna wycena na jeden lub dwa tygodnie pomijałaby różnice między istniejącymi systemami. Wydanie z maja 2026 dodało GetUetTagAuthKey i raport identyfikatorów kliknięć; sama zmiana daty dokumentacji nie dowodzi zmiany działania backendu.

1. Format żądania i dane dostępowe

Zdarzenia trafiają jako JSON do https://capi.uet.microsoft.com/v1/{tagId}/events, z kluczem CAPI tagu w Authorization: Bearer …. Tablica data zawiera maksymalnie 1000 zdarzeń. eventType przyjmuje custom lub pageLoad; eventTime oznacza czas Unix UTC w sekundach z poprzednich siedmiu dni. userData wymaga co najmniej jednego obsługiwanego identyfikatora. Odsłony wymagają także eventSourceUrl. Niestandardowe cele konwersji muszą odpowiadać skonfigurowanym właściwościom zdarzenia.

Oddzielne wywołanie Campaign Management korzysta z OAuth oraz wymaganych nagłówków dewelopera i konta. Te dane dostępowe nie są zamienne z kluczem CAPI. GetUetTagAuthKey pobiera istniejący klucz; utworzenie klucza przy braku wcześniejszego wymaga własności tagu. Ponowne pobranie nie wykonuje rotacji. Wygenerowanie zamiennika lub unieważnienie musi odbywać się zgodnie z obsługiwaną procedurą konta.

2. Rzeczywista rozbieżność dokumentacji i granice wnioskowania

W dniu kontroli, 24 października 2026, przewodnik pokazuje TagId i zagnieżdżoną odpowiedź TagAuthKey.AuthKey. Dokumentacja operacji podaje UetTagId i płaski UetTagAuthKey. To niespójność dokumentów, a nie dowód różnych kontraktów API dla poszczególnych kont. Żądanie powinno odpowiadać wybranemu SDK lub kontraktowi operacji i zostać sprawdzone w uprawnionym środowisku integracyjnym.

Adapter obsługuje słowniki i obiekty w obu opisanych postaciach, odrzuca zgłoszone błędy częściowe oraz sprzeczne klucze i nie zapisuje sekretu w logu. Dostęp jak do słownika następuje dopiero po sprawdzeniu typu odpowiedzi.

from collections.abc import Mapping

def field(value, name):
    return value.get(name) if isinstance(value, Mapping) else getattr(value, name, None)

def extract_auth_key(response):
    if field(response, "PartialErrors"):
        raise ValueError("Auth response contains errors; inspect redacted diagnostics")
    values = [field(response, "UetTagAuthKey"),
              field(field(response, "TagAuthKey"), "AuthKey")]
    keys = {v for v in values if isinstance(v, str) and v.strip()}
    if len(keys) != 1:
        raise ValueError("Missing or conflicting auth-key fields")
    key = keys.pop()
    if any(c.isspace() or ord(c) < 32 or ord(c) == 127 for c in key):
        raise ValueError("Invalid auth-key whitespace/control character")
    return key

Tolerancja schematu nie naprawia błędnych danych dostępowych ani nieprawidłowego żądania. Logi diagnostyczne powinny zawierać identyfikatory żądania/śledzenia, status i oczyszczoną klasyfikację błędu. Surowe odpowiedzi autoryzacji, nagłówki bearer i dane klientów nie należą do zwykłych logów. Odczyt nowego zatwierdzonego sekretu między paczkami ułatwia zmianę, lecz nie gwarantuje rotacji bez przerwy ani pomijalnego czasu dostępu do magazynu.

3. Deduplikacja wymaga więcej niż numeru zamówienia

Przeglądarkowa i serwerowa kopia tego samego zdarzenia wymagają tego samego tagu UET, zgodnej nazwy zdarzenia i stabilnego identyfikatora. JavaScript UET używa event_id, a CAPI eventId. Identyfikator powinien oznaczać zdarzenie biznesowe, na przykład zakończony zakup, i pozostać niezmieniony przy ponowieniach. Zakup i zwrot są różnymi zdarzeniami, nawet przy jednym zamówieniu.

Stabilność może zapewnić zapisany losowy identyfikator albo identyfikator zamówienia połączony z typem zdarzenia i przestrzenią nazw. Druga droga transportu nie może generować nowej losowej wartości. Zdarzenia CRM wysyłane wyłącznie serwerowo nie mają odpowiednika w przeglądarce, lecz nadal wymagają poprawnej obsługi ponowień. Stałe identyfikatory pomagają zapobiegać duplikatom; pojedyncze pole nie gwarantuje przetwarzania dokładnie raz mimo awarii.

4. Normalizacja poszczególnych pól i zgody

Obecne instrukcje Microsoftu dla e-maili obejmują usunięcie skrajnych białych znaków, kropek i aliasu z plusem z części lokalnej, zamianę na małe litery oraz SHA-256. To reguła dopasowania Microsoftu, a nie uniwersalna zasada edycji zapisanych kontaktów lub danych innych platform. Telefon jest hashowany w kanonicznym formacie E.164 wraz z początkowym plusem. Funkcja oczekuje już znormalizowanego numeru międzynarodowego; interpretacja kraju i walidacja rzeczywistego numeru należą do wcześniejszego etapu.

import hashlib
import re

def microsoft_email_hash(value):
    if not isinstance(value, str):
        return None
    value = value.strip()
    if value.count("@") != 1 or any(c.isspace() or ord(c) < 32 for c in value):
        return None
    local, domain = value.split("@")
    local = local.split("+", 1)[0].replace(".", "")
    if not local or not domain or "." not in domain:
        return None
    return hashlib.sha256((local + "@" + domain).lower().encode("utf-8")).hexdigest()

def microsoft_phone_hash(e164):
    if not isinstance(e164, str) or not re.fullmatch(r"\+[1-9][0-9]{6,14}", e164):
        return None
    return hashlib.sha256(e164.encode("utf-8")).hexdigest()

Funkcje stanowią celowo ograniczone przykłady, a nie pełne walidatory adresów i telefonów. Nieprawidłowe lub niedostępne identyfikatory powinny zostać pominięte zamiast zastąpione hashami wartości zastępczych. Adres IP, user agent i identyfikator kliknięcia mają osobne reguły; ogólna instrukcja hashowania każdego identyfikatora jest błędna. Hashowanie nie czyni też danych identyfikujących anonimowymi.

adStorageConsent przyjmuje G albo D. Według dokumentacji pominięcie pola oznacza domyślnie zgodę. Jawne przekazanie stanu ma więc znaczenie: zdarzenia z odmową nie są wykorzystywane do celów reklamowych, w tym atrybucji i remarketingu. Pole nie uprawnia do wysyłki danych osobowych, których przekazanie jest z innych powodów niedozwolone.

Aplikacja musi zapewnić dopuszczalną podstawę zbierania i wysyłania danych, zachować odpowiednie dowody zgody oraz ponownie sprawdzić obowiązujące wycofania i blokady przed wysyłką z kolejki. Wcześniejsza zgoda nie uzasadnia ignorowania późniejszego wycofania. Sprzedaż telefoniczna może mieć oddzielny zapis zgody; brak banera internetowego sam w sobie nie dowodzi ani zezwolenia, ani zakazu. Stan nieznany nie może automatycznie stać się zgodą.

5. Siedem dni, daty przyszłe i ostatnia godzina

Kontrola wieku musi odrzucać przyszłe daty bez usuwania ważnych rekordów tylko z powodu zbliżającego się terminu. Funkcja rozróżnia daty nieprawidłowe, przyszłe, wygasłe i pilne. Pilne zdarzenie nadal kwalifikuje się do natychmiastowej próby; próg ostrzegania nie skraca okna API. Kwalifikacja wymaga ponownej kontroli tuż przed wysyłką.

from datetime import datetime, timedelta, timezone

def event_age_state(event_time, now):
    if not isinstance(event_time, datetime) or not isinstance(now, datetime):
        return "invalid"
    if event_time.tzinfo is None or event_time.utcoffset() is None or now.tzinfo is None or now.utcoffset() is None:
        return "invalid"
    age = now.astimezone(timezone.utc) - event_time.astimezone(timezone.utc)
    if age < timedelta(0):
        return "future"
    if age >= timedelta(days=7):
        return "expired"
    if age >= timedelta(days=7, hours=-1):
        return "urgent"
    return "ready"

Granica dokładnie siedmiu dni jest ostrożnie traktowana jako wygaśnięcie. Funkcja zwraca wyłącznie stany; nie wysyła ani nie usuwa rekordów. Trwała kolejka wymaga jednoznacznych wyników, ograniczonego harmonogramu ponowień i ustalenia odpowiedzialności za trwające zadania. Po awarii workera dostarczenie może być niepewne; sama kolumna stanu nie dowodzi nieszkodliwego wznowienia. Stare zdarzenia nie mogą otrzymywać bieżącej daty w celu obejścia okna.

6. Sukces HTTP różni się od sukcesu zdarzenia

Przewodnik dokumentuje obecnie HTTP 400 dla błędów walidacji i 401 dla błędów autoryzacji. Odpowiedź 401 wymaga poprawienia danych dostępowych i powiązania tagu; niezmieniony błędny payload nie powinien być ponawiany bez końca po 400. Przejściowe błędy transportu lub usługi mogą uzasadniać ograniczone ponowienia z wykładniczym opóźnieniem i losowym rozproszeniem. Faktycznie otrzymana instrukcja Retry-After wymaga uwzględnienia; nie zakłada się nieudokumentowanego liczbowego limitu żądań.

Domyślnie błąd walidacji uniemożliwia przetworzenie całej paczki. Przy continueOnValidationError: true poprawne zdarzenia mogą zostać przetworzone, a nieprawidłowe pominięte. HTTP 200 może zatem zawierać błędy lub ostrzeżenia; ostrzeżenie może oznaczać usunięcie pola opcjonalnego. Przed oznaczeniem rekordów jako przyjęte konieczne jest uzgodnienie eventsReceived i szczegółów diagnostycznych. Dokumentacja ogranicza listę szczegółów błędów/ostrzeżeń do pierwszych dziesięciu pozycji. Brak rekordu na widocznej liście nie zawsze dowodzi przyjęcia.

Prostsza strategia początkowa pozostawia przetwarzanie częściowe wyłączone, waliduje lokalnie i oddziela nieprawidłowe rekordy do korekty. Monitoring powinien rozróżniać przyjęcie przez API, odrzucenie zdarzenia, usunięcie pola i późniejszą przypisaną konwersję. Logi zapisują bezpieczne identyfikatory oraz klasy błędów zamiast nieograniczonej treści odpowiedzi.

7. Monitoring i uzgadnianie danych

Przydatne miary obejmują wiek najstarszego oczekującego zdarzenia, rekordy pilne i wygasłe, percentyle opóźnienia, liczbę przyjętych zdarzeń, błędy walidacji, stan zgody i pokrycie wszystkimi obsługiwanymi identyfikatorami. „Brak hasha e-maila” nie oznacza „brak identyfikatora”; zdarzenie może zawierać msclkid lub inne akceptowane pole. Wygasłe rekordy mogą pochodzić z importu starej historii lub błędnych dat i nie dowodzą sześciodniowej awarii.

Skoki zgód lub pokrycia identyfikatorami uzasadniają analizę, lecz nie dowodzą konkretnego błędu formularza czy narzędzia zgód. Struktura ruchu, kanały pozyskania i rzeczywiste zmiany biznesowe również mogą zmieniać te wartości. Konwersje raportowane przez Microsoft nie muszą odpowiadać wszystkim przyjętym zamówieniom: dopasowanie, cele, okna, zasady zliczania, data raportowa i opóźnienie przetwarzania wpływają na porównanie.