Create a viral waiting list

Alice has created a new app (she describes it as "Pinterest for cats") and wants to generate hype before the launch. To do so she wants to create a competition that allows 100 people every week to get early access to the app.

People will sign up onto the list and invite their friends. They will get 1 point when signing up. For each person they invite they get 5 points. Also, if they upload a selfie of themselves with a cat they will get 10 extra points. At the end of every week she wants to give access to the top 100 in the list. 

NOTE
In our example we won't focus on security and testing too much. Hence, don't consider this example as production-ready.
Also, we are going to use Ruby on Rails as our back-end language of choice, but you are free to use any language you like.


Creating the signup form

The first step for Alice is to create a signup form to capture signups. Our form is located on the page https://pinterestforcats.com/competition.
In our example we will focus on the form itself, rather than the structure of the entire HTML page.

Here's the code Alice adds to the page that creates the signup form.

<form action="/subscribe" method="POST" enctype="multipart/form-data">
  <input type="hidden" name="ref" value="<%= params[:ref] %>">
  <div class="input-group">
    <label>Name</label>
    <input type="text" name="name">
  </div>
  <div class="input-group">
    <label>Email</label>
    <input type="email" name="email">
  </div>
  <div class="input-group">
    <label>Photo</label>
    <input type="file" name="file">
  </div>
  <div class="input-group">
    <input type="Submit" name="submit">
  </div>
</form>

Notice that in our example we collect Name, Email and Photo. In your application you might want to collect more information.

Subscribe user to a list using Maître API

Once the user submits the form and the request hits the back-end, it's time to use Maître APIs.
We'll use the "subscribe user to a list" endpoint. You can check all the available options  here.

/subscribers_controller.rb
def subscribe
  @name = params[:name]
  @email = params[:email]
  @file = params[:file]
  @ref = params[:ref]

  sub = Subscriber.signup(@name, @email, @file, @ref)

  if sub
   redirect_to thank_you_path(sub)
  else
   redirect_back
  end
end

In our controller we simply retrieve the parameters and create the subscriber.

/subscriber.rb
def self.signup(name, email, file, ref)

  require 'net/http'
  require 'uri'

  is_cat_photo = Image.is_cat?(file) // Revolutionary technology that detects selfies with cats. Returns true or false

  # Set variables
  uuid = "YOUR_LIST_UUID"
  base_url = "https://maitreapp.co/api/v2/lists/#{uuid}/subscribers"
  payload = {
    api_token: "YOUR_API_TOKEN",
    hosting_url: "https://pinterestforcats.com/competition",
    email: email,
    name: name,
    points: (is_cat_photo ? 11 : 1), // Give 10 extra points if they upload cat photo
    referral: ref,
    referral_points: 5 // We assign 5 points for a successful referral
  }

  # Send the request
  response = Net::HTTP.post_form(URI(base_url), payload)

  if response["status"] == "ok"
    # API call successful
    sub = Subscriber.create!(
      name: name,
      email: email,
      maitre_id: response["data"]["id"],
      code: response["data"]["code"]
    )
    return response["data"]["id"]
  else
    # Something went wrong. Check the "Error page"
    return false
  end
end

In our model we use Maître's API to subscribe the user to the list. A few things to notice:

  • The "uuid" value is your list unique UUID. You can get this value from the "Code" tab in your widget dashboard.
  • The "points" value will be either 11 or 1, whether they upload a selfie with a cat. Points is very important because it will be used to determine the ranking (along with other factors. Read here the full explanation). If "points" is not provided the default value will be 1.
  • If the call is successful (response == "ok") you should store the some of the value returned in your database. You should definitely do this at least for the subscriber ID and the code because you will need both at some point, either when retrieving the subscriber information or when displaying the referral link.
  • The "code" value in the response is the unique referral code. We will see in a second how to create the referral link.
  • The "referral_points" value is set to 5 because we want to assign 5 points to the referrer. This parameter is optional. The default value is 1. If you feel creative you can use this parameter to create multiple levels of incentives. Eg: referrers get 5 points when they invite a friend and 10 points when they invite a friend who also uploads a selfie with a cat.

In our example we return the newly created subscriber id if the call is successful, otherwise we return false.
As we have seen above we use this info to redirect the user to the right page after the form submission. If the user is successfully subscribed, we redirect them to the "Thank you" page where we'll show them their referral link.

Thank you page and show referral link

On the "Thank you" page we finally thanks the user for signing up but most importantly we want to give them their referral link that they can use to invite their friends and earn points.

In the Thank you page we'll see how to use another endpoint to retrieve the subscriber's info.

pages_controller.rb
def thank_you
  @sub = Subscriber.retrieve(params[:id])

  unless @sub
    redirect_to root_path
  end
end
subscribers_controller.rb
def self.retrieve(subscriber_id)

  require 'net/http'
  require 'uri'

  # Set variables
  uuid = "YOUR_LIST_UUID"
  api_token = ENV['MAITRE_API_TOKEN']
  url = "https://maitreapp.co/api/v2/lists/#{uuid}/subscribers/#{subscriber_id}?api_token=#{api_token}"

  # Send the request
  response = Net::HTTP.get(URI(url))

  if response["status"] == "ok"
    return response["data"]
  else
    # Something went wrong. Check the "Error page"
    return false
  end
end
thank_you.html.erb
<h2>Thank you <%= @sub["name'] %> for signing up!</h2>

<p>This is your referral link: https://pinterestforcats.com/competition?ref<%= @sub["code"] %></p>

<p>You are #<%= @sub["position"] %> in the waiting list, but you can still be in the top 100 for this week!</p>
<p>For each friend you invite you earn 5 points and get ahead in the queue :)</p>

A few things to notice:

  • In our example we use the "view a single user" endpoint purely for example purposes. In your application you might want to store the data in your database to retrieve them more easily and quickly.
  • We create the referral link by adding a "ref" parameter with the "sub.code" value to the url. This is very important. As you might have noticed in the form we have created above, we send an hidden value "ref". We then use this value to assign the sign-up to the right referrer. Please notice that the parameter can called whatever you want, as long as you grab the value and pass it onto the API call.

Going live

Once the flow has been tested and everything works ok, Alice is ready to go live. Pinterest for Cats becomes a huge success, raises hundreds of billions and makes all cats owner happier.

Questions?

We're always happy to help with code or other questions you might have! Search our documentation and if you don't find what you are looking for send us an email.

Still need help? Contact Us Contact Us