ti.to referral tracker

ti.to is an event ticketing system. We use it at Copenhagen .NET Usergroup when we arrange events and conferences like MicroCPH.dk or Intelligent Cloud Conference.

An easy way to attract attention to an event is by using a referral program, where both the attendee and the potential attendee gain a benefit, providing an incentive for the attendee to share the event with friends and collegues.

Referral tracing

A ticket is assigned to an attendee
ti.to webhook calls the service
The service creates a ti.to Discount with code e.g. YAZR-1
The service creates a direct link to the tickets with the Discount applied
The service sends an email to the attendee with the direct ticket link with discount, which is used to track referral
If the Discount is applied to one of the valid tickets ticket (e.g. not free tickets), then a thank you email is send to the referrer. If a ticket is re-assigned, then the new attendee will receive a email, but the referrer will not be notified.

To figure out how many referrals each attendee has, compare the attendee code with the discount code. ti.to keeps track of how many times a Discount has been used.

When an user enters a discount code, tickets where the discount code applies are discounted, but other tickets are shown too. Only if the user purchase tickets where discount applies, will the referral system record it. ti.to will however still include the discount code in the ticket.completed webhook event.

Technology

The solution is build as a ASP.NET Core 2.2 Web API solution running on Linux, Mac & Windows.

Hosting

All you need is a web server. No database or similar.

At startup the configuration is validated and the process will fail without a valid configuration. If hosting in Azure Web Apps, a simple way of getting detailed error messages is adding ASPNETCORE_DETAILEDERRORS = true in the application settings.

Integration

We integrate with the ti.to Admin API.

Use the Webhook ticket.completed event to trigger the workflow
Create a unique discount for each attendee, they can use as referral
Create a direct ticket link with discount
Gmail is used for sending emails.
Azure Application Insights is used for tracing and logging.

Security

The solution verifies the webhook payload via the HTTP header tito-signature by using HMAC digest with SHA2 in the TitoPayloadVerifierMiddleware for all Web API requests. The security token used as key can be found under Customice | Webhooks in the ti.to admin portal.

To access the ti.to Admin API an API token is needed. To get your API Token go here.

Configuration

The configuration is validated at startup and the process will fail without a valid configuration.

{
  "Tito": {
    "AccountName": "<ti.to account slug e.g. CNUG>",
    "ApiToken": "<API Token>",
    "FromEmail": "email@confx.com",
    "FromName": "ConfX",
    "GmailEmailUsername": "email@confx.com",
    "GmailEmailPassword": P@ssword",
    "MandrillAppApiKey": "<Your API Key>",
    "Event": {
      "EventName": "<ti.to event slug e.g. my-conf-2019>",
      "WebHookSecurityToken": "<webhook security token>",
      "DiscountPct": false,
      "DiscountValue": <discount value e.g. 10.0>,
      "TicketIds": [
        "<ticket identifier where the discount is valid e.g. 43asdfd-c34>"
      ]
    }
  }
}

Be aware that slugs are case sensitive.

There are two options for sending email - either via Gmail or MandrillApp. If using Gmail use GmailEmailUsername and GmailEmailPassword, if using MandrillApp use MandrillAppApiKey. The Startup.cs file controles which email sender being used via Dependency Injection. Default is MandrilApp.

To find the TicketIds (called releases at API level), go to Tickets, select a ticket. The URL will include the TicketId e.g. https://ti.to/cnug/my-conf-2019/admin/releases/<TicketId>

ti.to setup

Go to the admin dashboard.

Customize | Webhooks and add https://<url>/api/titowebhook and select the ticket.completed only.

ti.to has a webhook log: https://api.tito.io/<account_slug>/<event_slug>/webhooks

Email templates

The system uses two HTML templates:

Referral Template send to the attendee when assigned at ticket.
Referral Thanks send to referrer when referral discount code is used.

The templates for Gmail are stored in EmailTemplates folder and the system expects them to be stored EmailTemplates folder and the executable root. If using MandrillApp, then use the same template names.

Running locally

Run in locally in .NET Core CLI dotnet run or in Visual Studio. It starts a web server on port 5000. Test it works by browsing to http://localhost:5000/api/titowebhook.

Testing ti.to webhook locally

Use ngrok to expose the web server to the public internet, by installing ngrok and running the following command

ngrok http -host-header="localhost:5000" 5000

Remeber to add the ngrok endpoint as a ti.to webhook.

Lybecker / tito-referral