Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(workflows): report each failed row in the push token batch api (#129104)

Daniel Marchuk4de68a252127
diff --git a/posthog/api/integration.py b/posthog/api/integration.py
index c5b59fa62202..a470bd3f0b0f 100644
--- a/posthog/api/integration.py
+++ b/posthog/api/integration.py
@@ -1710,6 +1710,12 @@ class IntegrationViewSet(
return [*base_permissions, TeamMemberLightManagementPermission()]
raise NotImplementedError()
+ def dangerously_get_required_scopes(self, request: Request, view: Any) -> list[str] | None:
+ # Importing devices writes person properties and tells which distinct IDs have a person.
+ if self.action == "push_tokens":
+ return ["integration:write", "person:write"]
+ return None
+
def get_throttles(self):
if self.action == "refresh_github_repos":
return [GitHubRepositoryRefreshThrottle(), *super().get_throttles()]
@@ -2864,17 +2870,35 @@ class IntegrationViewSet(
},
summary="Import push device tokens",
description="Register existing device tokens, for example exported from another provider, on this push "
- "channel. Each token is stored encrypted on its person, as the mobile SDK stores it.",
+ "channel. Each token is stored encrypted on its person, as the mobile SDK stores it. A row fails when no "
+ "person has its distinct ID, unless create_missing_persons is set, or when the token is the wrong kind for "
+ "the channel. Send dry_run first to see every failure without storing anything.",
)
@action(methods=["POST"], detail=True, url_path="push_tokens")
def push_tokens(self, request: ValidatedRequest, **kwargs) -> Response:
+ # Session users skip API scopes, and access control checks only the integration scope_object.
+ if not self.user_access_control.check_access_level_for_resource("person", "editor"):
+ raise PermissionDenied("You need edit access to persons to import push devices.")
integration = self.get_object()
if not push_channel_app_id(integration):
raise ValidationError("Device tokens can only be imported into an APNs or Firebase push channel.")
- result = import_push_tokens(integration, request.validated_data["subscriptions"], integration.team.api_token)
+ data = request.validated_data
+ result = import_push_tokens(
+ integration,
+ data["subscriptions"],
+ integration.team.api_token,
+ dry_run=data["dry_run"],
+ create_missing_persons=data["create_missing_persons"],
+ import_id=data["import_id"],
+ )
return Response(
PushTokenImportResponseSerializer(
- {"imported": result.imported, "failed_distinct_ids": result.failed_distinct_ids}
+ {
+ "imported": result.imported,
+ "dry_run": result.dry_run,
+ "failed": result.failed,
+ "failed_distinct_ids": result.failed_distinct_ids,
+ }
).data
)
diff --git a/posthog/api/integration_push_tokens.py b/posthog/api/integration_push_tokens.py
index 0be13bf69d7d..26626ff43e88 100644
--- a/posthog/api/integration_push_tokens.py
+++ b/posthog/api/integration_push_tokens.py
@@ -1,5 +1,9 @@
+import re
import uuid
import hashlib
+from datetime import datetime
+
+from django.db import models
from rest_framework import serializers
@@ -7,18 +11,46 @@ from posthog.api.capture import capture_batch_internal
from posthog.dataclasses import frozen
from posthog.helpers.encrypted_fields import EncryptedFieldMixin
from posthog.integrations import IntegrationRecord
+from posthog.models.person.util import get_person_uuids_and_matched_distinct_ids
DEVICE_SUBSCRIPTION_PREFIX = "$device_push_subscription_"
MAX_SUBSCRIPTIONS_PER_REQUEST = 1000
+# Capture rejects a longer distinct ID, and it counts bytes, not characters.
+MAX_DISTINCT_ID_BYTES = 200
EVENT_SOURCE = "push_token_import"
+TOKEN_SUFFIX_LENGTH = 6
+
+# Expo tokens address Expo's own push service, so neither APNs nor FCM accepts them.
+_EXPO_TOKEN = re.compile(r"^Expo(nent)?PushToken\[.*\]$")
+# The iOS SDK hex-encodes the APNs device token. Apple documents the token as variable length,
+# so an APNs channel only checks the alphabet.
+_HEX_TOKEN = re.compile(r"^(?:[0-9a-fA-F]{2})+$")
+_APNS_TOKEN_MIN_HEX_LENGTH = 64
+
+
+class PushTokenImportFailureReason(models.TextChoices):
+ UNKNOWN_PERSON = "unknown_person", "No person has this distinct ID"
+ TOKEN_MISMATCH = "token_mismatch", "The token does not fit this channel"
+ NOT_STORED = "not_stored", "The device was not stored"
+ PERSON_PROCESSING_DISABLED = "person_processing_disabled", "Person processing is off for this person"
class PushTokenSubscriptionSerializer(serializers.Serializer):
- distinct_id = serializers.CharField(max_length=200, help_text="The person's distinct ID in this project.")
+ distinct_id = serializers.CharField(
+ max_length=200,
+ help_text="The person's distinct ID in this project: the ID your app passes to `identify`.",
+ )
device_token = serializers.CharField(
- max_length=4096, help_text="The APNs device token or FCM registration token of one device."
+ max_length=4096,
+ help_text="The token of one device. An APNs channel takes the hex APNs device token. "
+ "A Firebase channel takes the FCM registration token. Expo push tokens are not accepted.",
)
+ def validate_distinct_id(self, value: str) -> str:
+ if len(value.encode()) > MAX_DISTINCT_ID_BYTES:
+ raise serializers.ValidationError(f"Distinct ID is longer than {MAX_DISTINCT_ID_BYTES} bytes.")
+ return value
+
class PushTokenImportRequestSerializer(serializers.Serializer):
subscriptions: serializers.ListSerializer = serializers.ListSerializer(
@@ -28,20 +60,71 @@ class PushTokenImportRequestSerializer(serializers.Serializer):
help_text=f"Up to {MAX_SUBSCRIPTIONS_PER_REQUEST} devices to register on this push channel. "
"List a person once per device.",
)
+ dry_run = serializers.BooleanField(
+ default=False,
+ help_text="Check every row and report what would fail, without storing anything. "
+ "Run this first and fix the failed rows before importing.",
+ )
+ import_id = serializers.UUIDField(
+ required=False,
+ allow_null=True,
+ default=None,
+ help_text="A new UUID for each batch. Send the same value when you retry that batch, "
+ "so a retried batch can be recognized as a repeat.",
+ )
+ create_missing_persons = serializers.BooleanField(
+ default=False,
+ help_text="Create a person for a distinct ID that has none. Off by default, because a distinct ID "
+ "that does not match your app's identify call creates a person that never gets a push.",
+ )
+
+
+class PushTokenImportFailureSerializer(serializers.Serializer):
+ index = serializers.IntegerField(help_text="Position of the row in the request's `subscriptions`, from 0.")
+ distinct_id = serializers.CharField(help_text="The distinct ID of the row.")
+ device_token_suffix = serializers.CharField(
+ help_text=f"The last {TOKEN_SUFFIX_LENGTH} characters of the row's device token, to find the row."
+ )
+ reason = serializers.ChoiceField(
+ choices=PushTokenImportFailureReason.choices,
+ help_text="Why the device was not stored. `unknown_person`: no person has this distinct ID, so check "
+ "the ID or set `create_missing_persons`. `token_mismatch`: the token is the wrong kind for this channel, "
+ "for example an Expo token, or an APNs token on a Firebase channel. `not_stored` and "
+ "`person_processing_disabled`: ingestion did not store the device.",
+ )
+ detail = serializers.CharField(help_text="A sentence a person can act on.")
class PushTokenImportResponseSerializer(serializers.Serializer):
- imported = serializers.IntegerField(help_text="Number of devices stored on their person.")
+ imported = serializers.IntegerField(
+ help_text="Number of devices stored on their person. On a dry run, the number that would be stored."
+ )
+ dry_run = serializers.BooleanField(help_text="True when nothing was stored.")
+ failed = PushTokenImportFailureSerializer(many=True, help_text="One entry per device that was not stored.")
failed_distinct_ids = serializers.ListField(
child=serializers.CharField(),
- help_text="Distinct IDs with at least one device that was not stored. Send those rows again.",
+ help_text="Distinct IDs with at least one device that was not stored. Prefer `failed`, which says why.",
)
+@frozen
+class PushTokenImportFailure:
+ index: int
+ distinct_id: str
+ device_token_suffix: str
+ reason: PushTokenImportFailureReason
+ detail: str
+
+
@frozen
class PushTokenImportResult:
imported: int
- failed_distinct_ids: list[str]
+ dry_run: bool
+ failed: list[PushTokenImportFailure]
+
+ @property
+ def failed_distinct_ids(self) -> list[str]:
+ return sorted({failure.distinct_id for failure in self.failed})
class _TokenCipher(EncryptedFieldMixin):
@@ -62,24 +145,84 @@ def device_subscription_key(app_id: str, device_token: str) -> str:
return f"{DEVICE_SUBSCRIPTION_PREFIX}{app_id}:{digest}"
+def token_mismatch(kind: str, device_token: str) -> str | None:
+ """Says why a token cannot work on this kind of channel. Rejects only shapes that cannot fit."""
+ if _EXPO_TOKEN.match(device_token):
+ return "This is an Expo push token. Import the device's APNs or FCM token instead."
+ is_hex = bool(_HEX_TOKEN.match(device_token))
+ if kind == "apns" and not is_hex:
+ return "An APNs channel needs the hex APNs device token. This looks like an FCM or other token."
+ if kind == "firebase" and is_hex and len(device_token) >= _APNS_TOKEN_MIN_HEX_LENGTH:
+ return "This looks like an APNs device token. Import it into an APNs channel instead."
+ return None
+
+
def import_push_tokens(
- integration: IntegrationRecord, subscriptions: list[dict[str, str]], team_api_token: str
+ integration: IntegrationRecord,
+ subscriptions: list[dict[str, str]],
+ team_api_token: str,
+ *,
+ dry_run: bool = False,
+ create_missing_persons: bool = False,
+ import_id: uuid.UUID | None = None,
+ timestamp: datetime | None = None,
) -> PushTokenImportResult:
app_id = push_channel_app_id(integration)
if not app_id:
raise ValueError("This integration is not a push channel.")
+ failed: list[PushTokenImportFailure] = []
+
+ def fail(row: tuple[int, str, str], reason: PushTokenImportFailureReason, detail: str) -> None:
+ _, distinct_id, device_token = row
+ for index in indexes_by_device[(distinct_id, device_token)]:
+ failed.append(
+ PushTokenImportFailure(
+ index=index,
+ distinct_id=distinct_id,
+ device_token_suffix=device_token[-TOKEN_SUFFIX_LENGTH:],
+ reason=reason,
+ detail=detail,
+ )
+ )
+
+ rows: list[tuple[int, str, str]] = []
+ indexes_by_device: dict[tuple[str, str], list[int]] = {}
+ for index, subscription in enumerate(subscriptions):
+ key = (subscription["distinct_id"], subscription["device_token"])
+ if key in indexes_by_device:
+ indexes_by_device[key].append(index)
+ continue
+ indexes_by_device[key] = [index]
+ row = (index, *key)
+ if mismatch := token_mismatch(integration.kind, row[2]):
+ fail(row, PushTokenImportFailureReason.TOKEN_MISMATCH, mismatch)
+ else:
+ rows.append(row)
+
+ if rows and not create_missing_persons:
+ _, known = get_person_uuids_and_matched_distinct_ids(integration.team_id, sorted({d for _, d, _ in rows}))
+ for row in rows:
+ if row[1] not in known:
+ fail(
+ row,
+ PushTokenImportFailureReason.UNKNOWN_PERSON,
+ "No person has this distinct ID. Use the ID your app passes to identify, "
+ "or import with create_missing_persons.",
+ )
+ rows = [row for row in rows if row[1] in known]
+
+ if dry_run or not rows:
+ return PushTokenImportResult(imported=len(rows), dry_run=dry_run, failed=failed)
+
cipher = _TokenCipher()
events = []
- distinct_id_by_uuid: dict[str, str] = {}
- seen: set[tuple[str, str]] = set()
- for subscription in subscriptions:
- distinct_id, device_token = subscription["distinct_id"], subscription["device_token"]
- if (distinct_id, device_token) in seen:
- continue
- seen.add((distinct_id, device_token))
- event_uuid = str(uuid.uuid4())
- distinct_id_by_uuid[event_uuid] = distinct_id
+ row_by_uuid: dict[str, tuple[int, str, str]] = {}
+ for row in rows:
+ _, distinct_id, device_token = row
+ # A retried batch reuses its event IDs, so its copies can be deduplicated.
+ event_uuid = str(uuid.uuid5(import_id, f"{distinct_id}\n{device_token}") if import_id else uuid.uuid4())
+ row_by_uuid[event_uuid] = row
events.append(
{
"event": "$set",
@@ -88,6 +231,8 @@ def import_push_tokens(
# Encrypted, because the sender ignores a token it cannot decrypt as forged.
"properties": {"$set": {device_subscription_key(app_id, device_token): cipher.encrypt(device_token)}},
"options": {"process_person_profile": True},
+ # A retried batch reuses its timestamp too, because deduplication compares it with the event ID.
+ **({"timestamp": timestamp} if timestamp else {}),
}
)
@@ -98,13 +243,26 @@ def import_push_tokens(
process_person_profile=True,
)
# Capture skips the person update when person processing is disabled, so that device was never stored.
- skipped = {
+ skipped = [
event_uuid
for event_uuid in result.warnings
if result.results.get(event_uuid, {}).get("details") == "person_processing_disabled"
- }
- failed = {*result.dropped, *result.retried, *result.unaccounted, *skipped}
- return PushTokenImportResult(
- imported=len(events) - len(failed),
- failed_distinct_ids=sorted({distinct_id_by_uuid[event_uuid] for event_uuid in failed}),
- )
+ ]
+ not_stored = [
+ event_uuid
+ for event_uuid in (*result.dropped, *result.retried, *result.unaccounted)
+ if event_uuid not in skipped
+ ]
+ for event_uuid in skipped:
+ fail(
+ row_by_uuid[event_uuid],
+ PushTokenImportFailureReason.PERSON_PROCESSING_DISABLED,
+ "Person processing is off for this person, so the device was not stored.",
+ )
+ for event_uuid in not_stored:
+ fail(
+ row_by_uuid[event_uuid],
+ PushTokenImportFailureReason.NOT_STORED,
+ "Ingestion did not store this device. Send the row again.",
+ )
+ return PushTokenImportResult(imported=len(events) - len(skipped) - len(not_stored), dry_run=False, failed=failed)
diff --git a/posthog/api/test/test_integration_push_tokens.py b/posthog/api/test/test_integration_push_tokens.py
index e01a0f3f6aa4..16511fe264b6 100644
--- a/posthog/api/test/test_integration_push_tokens.py
+++ b/posthog/api/test/test_integration_push_tokens.py
@@ -1,6 +1,6 @@
from typing import Any
-from posthog.test.base import APIBaseTest
+from posthog.test.base import APIBaseTest, _create_person, flush_persons_and_events
from unittest.mock import patch
from parameterized import parameterized
@@ -10,7 +10,9 @@ from posthog.api.capture import CaptureInternalResult
from posthog.api.integration_push_tokens import MAX_SUBSCRIPTIONS_PER_REQUEST, _TokenCipher
from posthog.models.integration import Integration
from posthog.models.organization import Organization, OrganizationMembership
+from posthog.models.personal_api_key import PersonalAPIKey
from posthog.models.team import Team
+from posthog.models.utils import generate_random_token_personal, hash_key_value
def _capture_dropping(dropped_distinct_ids: set[str], warning_details: dict[str, str] | None = None):
@@ -49,15 +51,18 @@ class TestPushTokenImport(APIBaseTest):
config={"project_id": "example-project"},
)
- def _import(self, integration_id: int, subscriptions: list[dict[str, str]]):
+ def _import(self, integration_id: int, subscriptions: list[dict[str, str]], **options: Any):
return self.client.post(
f"/api/environments/{self.team.pk}/integrations/{integration_id}/push_tokens/",
- {"subscriptions": subscriptions},
+ {"subscriptions": subscriptions, **options},
format="json",
)
@parameterized.expand([("apns", "com.example.app"), ("firebase", "example-project")])
def test_stores_each_device_encrypted_under_the_key_the_sender_reads(self, kind: str, app_id: str) -> None:
+ for distinct_id in ["user-1", "user-2", "user-3", "user-4"]:
+ _create_person(team=self.team, distinct_ids=[distinct_id])
+ flush_persons_and_events()
capture, captured = _capture_dropping(
{"user-2"}, {"user-3": "person_processing_disabled", "user-4": "some_other_warning"}
)
@@ -67,15 +72,35 @@ class TestPushTokenImport(APIBaseTest):
[
{"distinct_id": "user-1", "device_token": "a1b2c3d4"},
{"distinct_id": "user-1", "device_token": "a1b2c3d4"},
- {"distinct_id": "user-1", "device_token": "second-device"},
- {"distinct_id": "user-2", "device_token": "dropped-device"},
- {"distinct_id": "user-3", "device_token": "skipped-device"},
- {"distinct_id": "user-4", "device_token": "warned-device"},
+ {"distinct_id": "user-1", "device_token": "b2c3d4e5"},
+ {"distinct_id": "user-2", "device_token": "c3d4e5f6"},
+ {"distinct_id": "user-3", "device_token": "d4e5f6a7"},
+ {"distinct_id": "user-4", "device_token": "e5f6a7b8"},
],
)
assert response.status_code == status.HTTP_200_OK, response.json()
- assert response.json() == {"imported": 3, "failed_distinct_ids": ["user-2", "user-3"]}
+ assert response.json() == {
+ "imported": 3,
+ "dry_run": False,
+ "failed": [
+ {
+ "index": 4,
+ "distinct_id": "user-3",
+ "device_token_suffix": "e5f6a7",
+ "reason": "person_processing_disabled",
+ "detail": "Person processing is off for this person, so the device was not stored.",
+ },
+ {
+ "index": 3,
+ "distinct_id": "user-2",
+ "device_token_suffix": "d4e5f6",
+ "reason": "not_stored",
+ "detail": "Ingestion did not store this device. Send the row again.",
+ },
+ ],
+ "failed_distinct_ids": ["user-2", "user-3"],
+ }
[call] = captured
assert call["token"] == self.team.api_token
assert call["process_person_profile"] is True
@@ -89,6 +114,84 @@ class TestPushTokenImport(APIBaseTest):
assert _TokenCipher().decrypt(value) == "a1b2c3d4"
assert len(call["events"]) == 5
+ def test_a_retried_batch_reuses_its_event_ids(self) -> None:
+ _create_person(team=self.team, distinct_ids=["user-1"])
+ flush_persons_and_events()
+ capture, captured = _capture_dropping(set())
+ subscriptions = [{"distinct_id": "user-1", "device_token": "a1b2c3d4"}]
+ with patch("posthog.api.integration_push_tokens.capture_batch_internal", side_effect=capture):
+ for import_id in [
+ None,
+ None,
+ "8f1a6f0e-2f4c-4b8e-9d55-3f0a3c2b1e10",
+ "8f1a6f0e-2f4c-4b8e-9d55-3f0a3c2b1e10",
+ ]:
+ options = {"import_id": import_id} if import_id else {}
+ assert self._import(self.apns.id, subscriptions, **options).status_code == status.HTTP_200_OK
+
+ no_id_first, no_id_retry, first, retry = [call["events"][0]["event_uuid"] for call in captured]
+ assert no_id_first != no_id_retry
+ assert first == retry
+
+ @parameterized.expand(
+ [
+ ("expo_on_apns", "apns", "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]"),
+ ("expo_on_firebase", "firebase", "ExpoPushToken[xxxxxxxxxxxxxxxxxxxxxx]"),
+ ("fcm_on_apns", "apns", "cK9dE2fGhIj:APA91bHqL0xYzExampleFcmRegistrationToken_-"),
+ ("apns_on_firebase", "firebase", "ab" * 32),
+ ]
+ )
+ def test_reports_a_token_of_the_wrong_kind(self, _name: str, kind: str, device_token: str) -> None:
+ _create_person(team=self.team, distinct_ids=["user-1"])
+ flush_persons_and_events()
+ with patch("posthog.api.integration_push_tokens.capture_batch_internal") as capture:
+ response = self._import(getattr(self, kind).id, [{"distinct_id": "user-1", "device_token": device_token}])
+ assert response.status_code == status.HTTP_200_OK, response.json()
+ assert response.json()["imported"] == 0
+ assert [f["reason"] for f in response.json()["failed"]] == ["token_mismatch"]
+ capture.assert_not_called()
+
+ @parameterized.expand(
+ [
+ ("rejected_by_default", {}, 1, ["unknown_person"]),
+ ("dry_run_reports_without_storing", {"dry_run": True}, 1, ["unknown_person"]),
+ ("created_when_asked", {"create_missing_persons": True}, 2, []),
+ ]
+ )
+ def test_a_distinct_id_with_no_person(
+ self, _name: str, options: dict[str, bool], imported: int, reasons: list[str]
+ ) -> None:
+ _create_person(team=self.team, distinct_ids=["known"])
+ flush_persons_and_events()
+ capture, captured = _capture_dropping(set())
+ with patch("posthog.api.integration_push_tokens.capture_batch_internal", side_effect=capture):
+ response = self._import(
+ self.apns.id,
+ [
+ {"distinct_id": "known", "device_token": "a1b2c3d4"},
+ {"distinct_id": "from-other-platform", "device_token": "b2c3d4e5"},
+ ],
+ **options,
+ )
+ assert response.status_code == status.HTTP_200_OK, response.json()
+ assert response.json()["imported"] == imported
+ assert [f["reason"] for f in response.json()["failed"]] == reasons
+ stored = [event["distinct_id"] for call in captured for event in call["events"]]
+ assert stored == ([] if options.get("dry_run") else ["known", "from-other-platform"][:imported])
+
+ def test_a_repeated_row_reports_each_of_its_indexes(self) -> None:
+ response = self._import(
+ self.apns.id,
+ [
+ {"distinct_id": "nobody", "device_token": "a1b2c3d4"},
+ {"distinct_id": "nobody", "device_token": "a1b2c3d4"},
+ ],
+ dry_run=True,
+ )
+
+ assert response.status_code == status.HTTP_200_OK, response.json()
+ assert [failure["index"] for failure in response.json()["failed"]] == [0, 1]
+
def test_rejects_an_integration_that_is_not_a_push_channel(self) -> None:
slack = Integration.objects.create(team=self.team, kind="slack", integration_id="T1", config={})
with patch("posthog.api.integration_push_tokens.capture_batch_internal") as capture:
@@ -96,6 +199,26 @@ class TestPushTokenImport(APIBaseTest):
assert response.status_code == status.HTTP_400_BAD_REQUEST
capture.assert_not_called()
+ @parameterized.expand(
+ [
+ ("integration_only", ["integration:write"], status.HTTP_403_FORBIDDEN),
+ ("with_person_write", ["integration:write", "person:write"], status.HTTP_200_OK),
+ ]
+ )
+ def test_an_api_key_needs_person_write_to_import(self, _name: str, scopes: list[str], expected: int) -> None:
+ token = generate_random_token_personal()
+ PersonalAPIKey.objects.create(label="t", user=self.user, secure_value=hash_key_value(token), scopes=scopes)
+ self.client.logout()
+ with patch("posthog.api.integration_push_tokens.capture_batch_internal") as capture:
+ response = self.client.post(
+ f"/api/environments/{self.team.pk}/integrations/{self.apns.id}/push_tokens/",
+ {"subscriptions": [{"distinct_id": "user-1", "device_token": "a1b2c3d4"}], "dry_run": True},
+ format="json",
+ HTTP_AUTHORIZATION=f"Bearer {token}",
+ )
+ assert response.status_code == expected, response.json()
+ capture.assert_not_called()
+
def test_cannot_import_into_another_teams_channel(self) -> None:
other_team = Team.objects.create(organization=Organization.objects.create(name="other"))
other_apns = Integration.objects.create(
@@ -112,6 +235,7 @@ class TestPushTokenImport(APIBaseTest):
("too_many", [{"distinct_id": "u", "device_token": "t"}] * (MAX_SUBSCRIPTIONS_PER_REQUEST + 1)),
("missing_token", [{"distinct_id": "u"}]),
("blank_distinct_id", [{"distinct_id": "", "device_token": "t"}]),
+ ("distinct_id_over_the_byte_limit", [{"distinct_id": "🎉" * 51, "device_token": "t"}]),
]
)
def test_rejects_invalid_rows_without_capturing(self, _name: str, subscriptions: list[dict[str, str]]) -> None:
diff --git a/products/integrations/frontend/generated/api.schemas.ts b/products/integrations/frontend/generated/api.schemas.ts
index 485886477f1f..175648f73655 100644
--- a/products/integrations/frontend/generated/api.schemas.ts
+++ b/products/integrations/frontend/generated/api.schemas.ts
@@ -856,12 +856,12 @@ export interface LinearTeamsResponseApi {
export interface PushTokenSubscriptionApi {
/**
- * The person's distinct ID in this project.
+ * The person's distinct ID in this project: the ID your app passes to `identify`.
* @maxLength 200
*/
distinct_id: string
/**
- * The APNs device token or FCM registration token of one device.
+ * The token of one device. An APNs channel takes the hex APNs device token. A Firebase channel takes the FCM registration token. Expo push tokens are not accepted.
* @maxLength 4096
*/
device_token: string
@@ -870,12 +870,59 @@ export interface PushTokenSubscriptionApi {
export interface PushTokenImportRequestApi {
/** Up to 1000 devices to register on this push channel. List a person once per device. */
subscriptions: PushTokenSubscriptionApi[]
+ /** Check every row and report what would fail, without storing anything. Run this first and fix the failed rows before importing. */
+ dry_run?: boolean
+ /**
+ * A new UUID for each batch. Send the same value when you retry that batch, so a retried batch can be recognized as a repeat.
+ * @nullable
+ */
+ import_id?: string | null
+ /** Create a person for a distinct ID that has none. Off by default, because a distinct ID that does not match your app's identify call creates a person that never gets a push. */
+ create_missing_persons?: boolean
+}
+
+/**
+ * * `unknown_person` - No person has this distinct ID
+ * * `token_mismatch` - The token does not fit this channel
+ * * `not_stored` - The device was not stored
+ * * `person_processing_disabled` - Person processing is off for this person
+ */
+export type PushTokenImportFailureReasonEnumApi =
+ (typeof PushTokenImportFailureReasonEnumApi)[keyof typeof PushTokenImportFailureReasonEnumApi]
+
+export const PushTokenImportFailureReasonEnumApi = {
+ UnknownPerson: 'unknown_person',
+ TokenMismatch: 'token_mismatch',
+ NotStored: 'not_stored',
+ PersonProcessingDisabled: 'person_processing_disabled',
+} as const
+
+export interface PushTokenImportFailureApi {
+ /** Position of the row in the request's `subscriptions`, from 0. */
+ index: number
+ /** The distinct ID of the row. */
+ distinct_id: string
+ /** The last 6 characters of the row's device token, to find the row. */
+ device_token_suffix: string
+ /** Why the device was not stored. `unknown_person`: no person has this distinct ID, so check the ID or set `create_missing_persons`. `token_mismatch`: the token is the wrong kind for this channel, for example an Expo token, or an APNs token on a Firebase channel. `not_stored` and `person_processing_disabled`: ingestion did not store the device.
+ *
+ * * `unknown_person` - No person has this distinct ID
+ * * `token_mismatch` - The token does not fit this channel
+ * * `not_stored` - The device was not stored
+ * * `person_processing_disabled` - Person processing is off for this person */
+ reason: PushTokenImportFailureReasonEnumApi
+ /** A sentence a person can act on. */
+ detail: string
}
export interface PushTokenImportResponseApi {
- /** Number of devices stored on their person. */
+ /** Number of devices stored on their person. On a dry run, the number that would be stored. */
imported: number
- /** Distinct IDs with at least one device that was not stored. Send those rows again. */
+ /** True when nothing was stored. */
+ dry_run: boolean
+ /** One entry per device that was not stored. */
+ failed: PushTokenImportFailureApi[]
+ /** Distinct IDs with at least one device that was not stored. Prefer `failed`, which says why. */
failed_distinct_ids: string[]
}
diff --git a/products/integrations/frontend/generated/api.ts b/products/integrations/frontend/generated/api.ts
index 8592d340a2a0..9a583848a918 100644
--- a/products/integrations/frontend/generated/api.ts
+++ b/products/integrations/frontend/generated/api.ts
@@ -840,7 +840,7 @@ export const getIntegrationsPushTokensCreateUrl = (projectId: string, id: number
}
/**
- * Register existing device tokens, for example exported from another provider, on this push channel. Each token is stored encrypted on its person, as the mobile SDK stores it.
+ * Register existing device tokens, for example exported from another provider, on this push channel. Each token is stored encrypted on its person, as the mobile SDK stores it. A row fails when no person has its distinct ID, unless create_missing_persons is set, or when the token is the wrong kind for the channel. Send dry_run first to see every failure without storing anything.
* @summary Import push device tokens
*/
export const integrationsPushTokensCreate = async (
diff --git a/products/integrations/frontend/generated/api.zod.ts b/products/integrations/frontend/generated/api.zod.ts
index d8aa94c806d0..4c7ba46ec01a 100644
--- a/products/integrations/frontend/generated/api.zod.ts
+++ b/products/integrations/frontend/generated/api.zod.ts
@@ -139,13 +139,16 @@ export const IntegrationsEmailPartialUpdateBody = /* @__PURE__ */ zod
.describe('Standard Integration serializer.')
/**
- * Register existing device tokens, for example exported from another provider, on this push channel. Each token is stored encrypted on its person, as the mobile SDK stores it.
+ * Register existing device tokens, for example exported from another provider, on this push channel. Each token is stored encrypted on its person, as the mobile SDK stores it. A row fails when no person has its distinct ID, unless create_missing_persons is set, or when the token is the wrong kind for the channel. Send dry_run first to see every failure without storing anything.
* @summary Import push device tokens
*/
export const integrationsPushTokensCreateBodySubscriptionsItemDistinctIdMax = 200
export const integrationsPushTokensCreateBodySubscriptionsItemDeviceTokenMax = 4096
+export const integrationsPushTokensCreateBodyDryRunDefault = false
+export const integrationsPushTokensCreateBodyCreateMissingPersonsDefault = false
+
export const IntegrationsPushTokensCreateBody = /* @__PURE__ */ zod.object({
subscriptions: zod
.array(
@@ -153,14 +156,34 @@ export const IntegrationsPushTokensCreateBody = /* @__PURE__ */ zod.object({
distinct_id: zod
.string()
.max(integrationsPushTokensCreateBodySubscriptionsItemDistinctIdMax)
- .describe("The person's distinct ID in this project."),
+ .describe("The person's distinct ID in this project: the ID your app passes to `identify`."),
device_token: zod
.string()
.max(integrationsPushTokensCreateBodySubscriptionsItemDeviceTokenMax)
- .describe('The APNs device token or FCM registration token of one device.'),
+ .describe(
+ 'The token of one device. An APNs channel takes the hex APNs device token. A Firebase channel takes the FCM registration token. Expo push tokens are not accepted.'
+ ),
})
)
.describe('Up to 1000 devices to register on this push channel. List a person once per device.'),
+ dry_run: zod
+ .boolean()
+ .default(integrationsPushTokensCreateBodyDryRunDefault)
+ .describe(
+ 'Check every row and report what would fail, without storing anything. Run this first and fix the failed rows before importing.'
+ ),
+ import_id: zod
+ .uuid()
+ .nullish()
+ .describe(
+ 'A new UUID for each batch. Send the same value when you retry that batch, so a retried batch can be recognized as a repeat.'
+ ),
+ create_missing_persons: zod
+ .boolean()
+ .default(integrationsPushTokensCreateBodyCreateMissingPersonsDefault)
+ .describe(
+ "Create a person for a distinct ID that has none. Off by default, because a distinct ID that does not match your app's identify call creates a person that never gets a push."
+ ),
})
/**
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index 6c020a0cbfd7..1943ad85f308 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -93654,14 +93654,48 @@ export namespace Schemas {
pins: PulsePin[];
}
+ /**
+ * * `unknown_person` - No person has this distinct ID
+ * * `token_mismatch` - The token does not fit this channel
+ * * `not_stored` - The device was not stored
+ * * `person_processing_disabled` - Person processing is off for this person
+ */
+ export type PushTokenImportFailureReasonEnum = typeof PushTokenImportFailureReasonEnum[keyof typeof PushTokenImportFailureReasonEnum];
+
+
+ export const PushTokenImportFailureReasonEnum = {
+ UnknownPerson: 'unknown_person',
+ TokenMismatch: 'token_mismatch',
+ NotStored: 'not_stored',
+ PersonProcessingDisabled: 'person_processing_disabled',
+ } as const;
+
+ export interface PushTokenImportFailure {
+ /** Position of the row in the request's `subscriptions`, from 0. */
+ index: number;
+ /** The distinct ID of the row. */
+ distinct_id: string;
+ /** The last 6 characters of the row's device token, to find the row. */
+ device_token_suffix: string;
+ /** Why the device was not stored. `unknown_person`: no person has this distinct ID, so check the ID or set `create_missing_persons`. `token_mismatch`: the token is the wrong kind for this channel, for example an Expo token, or an APNs token on a Firebase channel. `not_stored` and `person_processing_disabled`: ingestion did not store the device.
+ *
+ * * `unknown_person` - No person has this distinct ID
+ * * `token_mismatch` - The token does not fit this channel
+ * * `not_stored` - The device was not stored
+ * * `person_processing_disabled` - Person processing is off for this person */
+ reason: PushTokenImportFailureReasonEnum;
+ /** A sentence a person can act on. */
+ detail: string;
+ }
+
export interface PushTokenSubscription {
/**
- * The person's distinct ID in this project.
+ * The person's distinct ID in this project: the ID your app passes to `identify`.
* @maxLength 200
*/
distinct_id: string;
/**
- * The APNs device token or FCM registration token of one device.
+ * The token of one device. An APNs channel takes the hex APNs device token. A Firebase channel takes the FCM registration token. Expo push tokens are not accepted.
* @maxLength 4096
*/
device_token: string;
@@ -93670,12 +93704,25 @@ export namespace Schemas {
export interface PushTokenImportRequest {
/** Up to 1000 devices to register on this push channel. List a person once per device. */
subscriptions: PushTokenSubscription[];
+ /** Check every row and report what would fail, without storing anything. Run this first and fix the failed rows before importing. */
+ dry_run?: boolean;
+ /**
+ * A new UUID for each batch. Send the same value when you retry that batch, so a retried batch can be recognized as a repeat.
+ * @nullable
+ */
+ import_id?: string | null;
+ /** Create a person for a distinct ID that has none. Off by default, because a distinct ID that does not match your app's identify call creates a person that never gets a push. */
+ create_missing_persons?: boolean;
}
export interface PushTokenImportResponse {
- /** Number of devices stored on their person. */
+ /** Number of devices stored on their person. On a dry run, the number that would be stored. */
imported: number;
- /** Distinct IDs with at least one device that was not stored. Send those rows again. */
+ /** True when nothing was stored. */
+ dry_run: boolean;
+ /** One entry per device that was not stored. */
+ failed: PushTokenImportFailure[];
+ /** Distinct IDs with at least one device that was not stored. Prefer `failed`, which says why. */
failed_distinct_ids: string[];
}