IxDF Developer Docs

Appearance

Referral Program module overview ​

Background ​

We use referral programs to encourage our Members to invite other people to join the platform.

Glossary ​

  • Referral Programs: Referral programs are designed to encourage existing customers to help IxDF attract new customers.
  • Referrer (Partner): This is the person who invites someone to join the platform.
  • Referee (Friend): This is the person who receives the invitation and joins the platform.
  • Rewards: These are the benefits given to the Referrer and/or Referee when the referral is completed successfully.
  • Referral: The process of one person inviting another to join.

Available programs ​

We currently have two active programs, listed in order of priority:

  1. Refer a Friend (RaF) Program: This program is for individual Members who want to invite their friends to join IxDF.
  2. Educational Partner (EP) Program: This program is for Members or organizations affiliated with IxDF to promote the platform on external sites and social media and invite new Members in that way.

Every Member can participate in only one program at a time. Members who are enrolled into the Educational Partner program do not participate in the Refer a Friend program and vice versa.

Rewards ​

⚠️ Referral Programs may have asymmetric rewards, meaning the Referrer might receive rewards while the Referee does not, or the other way around.

Refer a Friend (RaF) program ​

  • Referrer earns x free months of Membership for every friend who joins the platform.
  • Referee gets y free months of Membership when signing up through a referral link.

Educational Partner (EP) program ​

  • Referrer receives x amount of money for every new Member who joins the platform (the commission is expressed as a percentage of the Membership fee).
  • Referee gets y free months of Membership upon signing up.

How it works ​

Our Members have a unique identifier called a slug that is used in referral links.

Referral program participants can use special links to invite others to join the platform:

  1. Refer a Friend (RaF): https://www.interaction-design.org/turn-passion-into-paycheck?r=member_slug
  2. Educational Partner (EP): https://www.interaction-design.org/turn-passion-into-paycheck?ep=member_slug

Key Difference: The two programs use different query parameter names (r for RaF and ep for EP).

When a visitor clicks a referral link:

  1. The app stores the query parameter’s value (which identifies the referrer) in a cookie.
  2. Each referral program has its own cookie (one for RaF and one for EP).
  3. Cookies cannot be overwritten. Once a cookie is set, it takes precedence, and new visits with other referral links won’t overwrite the stored value.

Referral program cookies ​

Cookie expiry is set for a very long time (up to 2 years) from the date of the first visit using a referral link.

Refer a Friend cookies can be overwritten. When a Refer a Friend referral program participant gets canceled, another Refer a Friend referral program participant can invite the same person to join the platform.

The IxDF has a policy to never overwrite Educational Partner cookies. If a visitor clicks multiple EP referral links, the first valid referral link sets the cookie, and it remains active until the cookie expires. This ensures that the first Educational Partner who brought the visitor to the site earns the commission. The only way to override this behavior is to clear the browser cookies.

Example scenario ​

  1. EP(1) does not offer access to free trials.
  2. A visitor clicks a referral link from EP(1), setting a cookie for EP(1).
  3. Later, the same visitor clicks a referral link from EP(2), who attempts to invite the visitor a free trial.
  4. In this case the visitor is redirected to the individual join flow with the following message: “Free Trial from EP(2) is not available at the moment. You can still sign up with a X-day money-back guarantee!”
  5. The cookie for EP(1) remains active, ensuring EP(1) is credited with the referral if the visitor signs up.

Why this matters?

This approach guarantees fairness by crediting the first Educational Partner who invited the visitor.

Multiple referral program cookies in the same browser ​

It’s possible for a visitor to have cookies set for both the Educational Partner (EP) and Refer a Friend (RaF) programs in the same browser. In such cases, the system uses the referral program priority to determine which program to apply. The RaF program has a higher priority and takes precedence over the EP program.

Educational Partners who transitioned from Refer a Friend referral program ​

After earning 3 full years of free membership through the Refer a Friend program, a referrer can voluntarily transition and become an Educational Partner. For this reason, we need to ensure that even when using the ?r=member_slug query parameter, the Educational Partner is credited with the referral.

Summary ​

  • Visiting a referral link sets a cookie that stores the Referrer’s identifier.
  • Different cookies are used for different programs (RaF and EP).
  • Once set, a cookie cannot be overwritten by another one from a different referral program participant.
  • If the visitor signs up within approximately 2 years, the Referrer and Referee both receive their respective rewards.
  • To avoid referral tracking, the visitor would need to clear their browser cookies.

Referral states ​

States for Referrer:

How do Referrals get awarded or forfeited? ​

Initially all Referrals are created in pending status. A scheduled command (called referral-programs:mark-referral-awarded-or-forfeited) runs periodically and updates the status of pending Referrals to awarded or forfeited.

For the Referral to be awarded the Member must not cancel their Membership within a certain period of time (see ixdf_referral_program.sign_up.award_after_days_on_referred_membership config variable). This requirement is in place to verify that the Member has not canceled their Membership shortly after registration, during the money-back guarantee period.

If the Member has canceled the membership within the money-back guarantee period, the Referral is marked as forfeited.

Membership Referral lifecycle ​

Trial Membership ​

Auto-appended invitation query parameters ​

Referral program invitation query parameters are not limited to specific URLs like /turn-passion-into-paycheck. For authenticated Members, we’ve modified Laravel’s core functionality to automatically append invitation query parameters to the most popular URLs on the site. For example, instead of /courses, Members might see /courses?r=member_slug.

To achieve this, we overrode Laravel’s default router behavior. Please note, the route() helper makes use of the router under the hood. We can continue using it just as normal.

Generating URLs without invitation query parameters ​

If you need to generate a URL without any invitation query parameters, use the following:

  • Helper Function: route_without_invite()
  • Method: url()->routeWithoutInvite()
php
// Adds invitation parameters for authenticated members
route('publication.books.show', $book); // https://www.interaction-design.org/literature/book/gamification-at-work-designing-engaging-business-software?ep=uxness

// Does not add invitation parameters
route_without_invite('publication.books.show', $book) //  https://www.interaction-design.org/literature/book/gamification-at-work-designing-engaging-business-software

How to get a Referrer from a request? ​

Example:

php
/** @var Member|null $referrer */
$referrer = \App\Modules\ReferralProgram\Services\ReferrerResolver::findReferrer($request);