Skip to main content

Friend-source Tracking

Overview​

Friend Track answers the question "where did this friend come from?" Administrators create a campaign-specific link or QR code; when a user adds the OA as a friend through that link, the system records the event and can immediately write the acquisition source into that friend's attributes.

It also supports sub-level ref IDs — staff codes, branch codes, or media codes — which can be uploaded as a batch in advance, allowing attribution to be broken down more finely than the campaign level.

Core Data Structure​

friend_track_campaign (model FriendTrackCampaign)​

  • name, description, token (unique, used to build the add-friend link), and status (string, default active)
  • attribute_config JSONB — which values to write into the user's attributes when they arrive through this campaign
  • ref_attribute_key — the attribute key that stores the ref ID
  • ref_upload_status JSONB — the status of the ref batch upload
  • foreign keys line_oa_id → line_oa.id and organization_id → organization.id, both ON DELETE Restrict

It has 1 : N relations to friend_track_event, friend_track_ref, and content_page, since a content page can carry an add-friend button for the campaign.

friend_track_event (model FriendTrackEvent)​

Records what actually happened.

  • campaign_id FK (ON DELETE CASCADE), line_user_id, event_type
  • a profile snapshot at the time: display_name and picture_url
  • ref_id — the sub-level ref carried by the link
  • indexes on (campaign_id), (line_user_id, line_oa_id), and (event_type, campaign_id)

friend_track_ref (model FriendTrackRef)​

The registry of permitted refs, with unique (campaign_id, ref_id) and a foreign key to friend_track_campaign using ON DELETE CASCADE.

Trigger​

friend_track_event_insert_notify (AFTER INSERT) calls notify_friend_track_event_insert(), emitting pg_notify('friend_track_event_inserted', ...).

Historical note — this trigger was once missing from the database: the function existed but the trigger itself did not, leaving the channel entirely silent. It was restored on 24 July 2026 in manual-sql/5.sql.

  • prisma/schema.prisma:1388 — model FriendTrackCampaign
  • prisma/schema.prisma:1418 — model FriendTrackEvent
  • prisma/schema.prisma:1439 — model FriendTrackRef
  • manual-sql/5.sql — the function and trigger, with comments explaining the fix
  • schema-dumps/2026-07-24/schema.sql:1869, :1912, :1950

Connections to Other Services​

  • webhook-go — receives follow events carrying a ref and inserts friend_track_event
  • worker-go — listens on friend_track_event_inserted to write attributes per attribute_config, add the user to audiences, and fire workflows
  • cms-api-go — campaign creation, ref batch uploads, and channel-level reporting through the friend-track module
  • client-api-go — content pages carrying the campaign's add-friend button

Related domains: LINE Friends, Attribute Master, Content Pages, Event Outbox