Skip to content

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_band enum
  • 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-events backed by the activation_events table. The backend derives role and a salted anonymousUserKey; mobile emits icp_units_selected and qualified_signup after 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.