Activation Event Taxonomy¶
Last updated: 2026-06-14.
This is the implementation contract for Epic 2 activation measurement. It defines the product events needed to prove owner activation during the paid pilot. It does not define a warehouse, dashboard, or analytics vendor.
Goals¶
- Measure whether qualified self-managing landlords move real workflows into MamNajem.
- Segment activation by role, unit count band, management model, plan, and pilot cohort without collecting personal data in analytics events.
- Emit events from the action that proves completion, not from screen views.
- Give frontend and backend one event/property contract to implement in EP2-T2, EP2-T3, and EP2-T4.
Emission Rules¶
- Event names use
snake_case. - Events must be emitted after the backend confirms the state change, except
icp_units_selected, which is emitted after the ICP onboarding values are saved successfully. - For backend-owned writes, prefer backend emission or a frontend event driven by a successful API response. Do not emit success events from button taps.
- Each event must include
app_environment,role, and an anonymized user or account key when available. - Events may include counts and bands, but must not include raw database IDs, emails, names, phone numbers, addresses, IBANs, document names, file names, rent amounts, free-text descriptions, messages, notes, or request payloads.
Common Properties¶
These properties are allowed on any activation event when the value is known. Later instrumentation should add them to the telemetry allowlist.
| Property | Type | Allowed values / format | Notes |
|---|---|---|---|
app_environment |
string | local, integration, production |
Required. |
platform |
string | ios, android, web |
Client platform when emitted client-side. |
role |
string | owner, tenant, unknown |
Required; activation reporting focuses on owner. |
anonymousUserKey |
string | Salted stable hash | Never send raw user IDs or Cognito subject values. |
anonymousAccountKey |
string | Salted stable hash | Owner/account-level key when available. |
source |
string | Stable route or workflow key | Example: onboarding, property_form, lease_form. |
pilot_cohort |
string | pilot, organic, internal, unknown |
Used to separate pilot users from organic users. |
unit_count_band |
string | 1, 2-3, 4-5, 6-10, 11-25, 26-50, 51+, unknown |
Band only; never send exact portfolio size. |
management_model |
string | self_managed, agency_managed, mixed, unknown |
Captured in EP2-T2. |
city_band |
string | warsaw, krakow, wroclaw, gdansk, poznan, lodz, katowice, other_poland, outside_poland, unknown |
City bucket only; do not send street or full address. |
plan |
string | trial, solo, portfolio, plus, archive, none, unknown |
Current effective plan/tier. |
subscription_status |
string | trial, active, archive, grace_period, canceled, expired, unknown |
Current effective subscription state. |
Event Contract¶
| Event | Trigger | Owner | Required properties | Optional properties |
|---|---|---|---|---|
qualified_signup |
Owner onboarding/ICP save confirms the user is in the first-release ICP: owner role, self-managed or mixed, Poland-oriented, and unit_count_band up to 11-25. |
Frontend after backend save, or backend profile service. | app_environment, role, anonymousUserKey, unit_count_band, management_model, pilot_cohort |
platform, source, city_band, plan, subscription_status |
icp_units_selected |
ICP onboarding unit-count step is saved successfully. Emit even when the user is not qualified. | Frontend after backend save. | app_environment, role, anonymousUserKey, unit_count_band |
platform, source, management_model, city_band, pilot_cohort |
property_created |
POST /v1/properties succeeds and creates a property. |
Backend properties service preferred; frontend success response acceptable. | app_environment, role, anonymousUserKey, property_count_band_after |
platform, source, unit_count_band, management_model, city_band, plan, subscription_status, property_kind |
lease_created |
POST /v1/leases succeeds and creates a lease. |
Backend lease service preferred; frontend success response acceptable. | app_environment, role, anonymousUserKey, lease_count_band_after |
platform, source, unit_count_band, management_model, plan, subscription_status, lease_type, rent_schedule_present |
document_uploaded |
Asset upload succeeds and the document is attached to a supported entity. | Backend asset service preferred; frontend success response acceptable. | app_environment, role, anonymousUserKey, asset_kind, linked_entity_type |
platform, source, file_kind, unit_count_band, management_model, plan, subscription_status |
rent_schedule_created |
A lease payment schedule is created, either during lease creation or via the payment schedule endpoint. | Backend payment schedule service preferred. | app_environment, role, anonymousUserKey, schedule_frequency |
platform, source, unit_count_band, management_model, plan, subscription_status, lease_type, created_with_lease |
payment_request_sent |
A rent payment request is created and is ready for tenant visibility or notification. | Backend payment request service preferred. | app_environment, role, anonymousUserKey, request_kind |
platform, source, unit_count_band, management_model, plan, subscription_status, delivery_channel, due_date_bucket |
payment_proof_uploaded |
A receipt/proof upload succeeds for a payment request. | Backend receipt service preferred; frontend success response acceptable. | app_environment, role, anonymousUserKey, proof_kind |
platform, source, unit_count_band, management_model, plan, subscription_status, actor_role |
handover_started |
A move-in or move-out handover protocol is created. | Backend handover service preferred. | app_environment, role, anonymousUserKey, handover_type |
platform, source, unit_count_band, management_model, plan, subscription_status, asset_count_band |
handover_completed |
A handover protocol reaches its confirmed/completed state. | Backend handover service preferred. | app_environment, role, anonymousUserKey, handover_type, completion_method |
platform, source, unit_count_band, management_model, plan, subscription_status, tenant_participation |
tenant_invited |
Tenant invitation is created successfully. | Backend invitation service preferred; frontend success response acceptable. | app_environment, role, anonymousUserKey, invite_channel |
platform, source, unit_count_band, management_model, plan, subscription_status, tenant_count_band_after |
second_live_unit_activated |
Owner reaches two active properties that each have at least one active lease or active rent workflow. Emit once per owner. | Backend activation milestone job/service. | app_environment, role, anonymousUserKey, activation_rule_version |
platform, source, unit_count_band, management_model, plan, subscription_status |
subscription_started |
Trial starts or paid subscription becomes active. | Backend subscription service. | app_environment, role, anonymousUserKey, plan, subscription_status, subscription_source |
platform, source, unit_count_band, management_model, billing_period |
subscription_canceled |
Subscription is canceled, deleted, or moved to non-renewing canceled state. | Backend subscription service. | app_environment, role, anonymousUserKey, plan, subscription_status, subscription_source |
platform, source, unit_count_band, management_model, billing_period, cancel_reason_bucket |
pilot_case_study_approved |
Product Owner records that a pilot participant approved case-study use. | Admin or backend pilot ops service. | app_environment, role, anonymousUserKey, pilot_cohort |
source, unit_count_band, management_model, case_study_scope |
Property Value Rules¶
| Property | Allowed values / format |
|---|---|
property_count_band_after, lease_count_band_after, tenant_count_band_after |
0, 1, 2, 3, 4-5, 6-10, 11-25, 26+, unknown |
property_kind |
apartment, house, room, commercial, other, unknown |
lease_type |
occasional, standard, institutional, unknown |
rent_schedule_present, created_with_lease |
boolean |
asset_kind |
Existing backend asset category, normalized to a stable enum. |
linked_entity_type |
property, lease, handover, payment_request, other |
file_kind |
pdf, image, document, spreadsheet, other, unknown |
schedule_frequency |
monthly, quarterly, one_time, other, unknown |
request_kind |
rent, deposit, utility, settlement, other, unknown |
delivery_channel |
in_app, email, sms, manual, none, unknown |
due_date_bucket |
overdue, 0-7_days, 8-30_days, 31+_days, none, unknown |
proof_kind |
manual_receipt, bank_transfer_confirmation, stripe_payment, other, unknown |
actor_role |
owner, tenant, admin, unknown |
handover_type |
move_in, move_out, other, unknown |
completion_method |
owner_confirmed, tenant_confirmed, both_confirmed, admin_recorded, unknown |
tenant_participation |
invited, viewed, confirmed, none, unknown |
asset_count_band |
0, 1, 2-3, 4-10, 11+, unknown |
activation_rule_version |
Stable string, starting with second_live_unit_v1. |
subscription_source |
trial, stripe, google_play, apple_app_store, grandfathered, unknown |
billing_period |
monthly, annual, none, unknown |
cancel_reason_bucket |
user_canceled, payment_failed, trial_expired, admin_revoked, unknown |
case_study_scope |
anonymous_quote, named_quote, logo_reference, full_case_study, unknown |
PII And Sensitive Data Blocklist¶
Activation events must never include:
- raw user, owner, tenant, lease, property, payment, receipt, Stripe, Google, or Apple IDs
- names, surnames, company names, tenant names, or landlord names
- email addresses, phone numbers, postal addresses, street names, apartment
numbers, postal codes, or exact city text outside the
city_bandenum - IBANs, bank names tied to a person, payment card details, tax IDs, PESEL, or identity-document values
- rent amounts, deposit amounts, fee amounts, prices, balances, currency amounts, or settlement values
- document titles, file names, message bodies, notes, descriptions, problem report text, lease clauses, or uploaded document contents
- request/response bodies, tokens, checkout URLs, signed upload URLs, webhook payloads, stack traces, or free-form errors
Reporting Questions This Enables¶
- How many qualified owners signed up this week?
- What share of qualified owners created at least one property?
- What share created a lease, rent schedule, tenant invite, payment request, or handover?
- How many owners activated a second live unit?
- How do trial starts, paid starts, and cancellations vary by unit count band?
- Which pilot users produced case-study-ready outcomes?
Implementation Notes For Later Tasks¶
- EP2-T2 stores ICP values in a backend-supported user profile model and exposes only enums/bands for analytics segmentation.
- EP2-T3 implements the internal activation destination as
POST /v1/activation-eventsbacked by theactivation_eventstable. The backend derivesroleand a saltedanonymousUserKey; mobile emitsicp_units_selectedandqualified_signupafter the ICP save succeeds. - EP2-T4 implements the first weekly Product Owner review surface as the
web-admin Activation page backed by
GET /v1/admin/activation-overview. Qualified signup and cohort segmentation come from activation events; workflow, second-unit, and subscription metrics are derived from backend tables until the remaining event contract is instrumented.