Refer a friend

phantom.aj.referralsOther players

Referrals.

Scripts and plugins

A script has all of it, as phantom.aj.referrals, and so does a plugin, from ctx.phantom(): the SDK runs in the plugin's own frame. Each call is marked with what it needs: game:read for what the area knows and hears, which "game": "read" in the manifest grants, and game:act for doing things in it as the player, which needs "game": "act" (see Permissions).

Overview

Member	What it does	Plugins
code()	Asks Animal Jam for the player's referral code (sendCodeRequest, refc), and resolves with it and its link.	game:act
everyone()	Everybody who joined with the player's code, every page, each player once.	game:act
hasReferrer()	Asks whether the player has already named who referred them (sendHasReferralAssociate, refh), as the buddy list does for a new account.	game:read
knownCode()	The code the client's refer a friend popup fetched this sitting (ReferAFriend.code), or null.	game:read
list()	A page of the players who joined with the player's code (sendReferralReferralsRequest, refr), page 1 first in pages of 8, as the "my referrals" panel asks.	game:read
nameReferrer()	Names the player who referred this one (sendReferralAssociation, refa), for good, as the "how did you hear about us" popup does.	game:act
rewards()	The four treasures the refer a friend popup shows, read from the account's two stats.	game:read
onCode()	Hears the referral code arrive, whoever asked; null when the server gave none.	game:read
onHasReferrer()	Hears each answer to whether a referrer is named, whoever asked.	game:read
onList()	Hears each page of referrals arrive, whoever asked; more is false, the page being unknown.	game:read
onReferrerNamed()	Hears each answer to naming a referrer, whoever named them: null when recorded, else why not.	game:read
onRewards()	Hears a referral treasure open, with the rewards as they stand after.	game:read

Methods

code

methodplugins · game:act

code(options?: ActOptions) => Promise<ReferralCode>

Asks Animal Jam for the player's referral code (sendCodeRequest, refc), and resolves with it and its link. Throws REFUSED when the server gives none.

Parameters

Name	Type
options optional	ActOptions

Returns

Promise<ReferralCode>

Types

ActOptions · ReferralCode

everyone

methodplugins · game:act

everyone(options?: ActOptions & { pageSize?: number | undefined; pages?: number | undefined; }) => Promise<ReferredPlayer[]>

Everybody who joined with the player's code, every page, each player once. It stops where the panel stops (a short page, or a later page refused) and at pages at most (50).

Parameters

Name	Type
options optional	ActOptions & { pageSize?: number | undefined; pages?: number | undefined; }

Returns

Promise<ReferredPlayer[]>

Types

ActOptions · ReferredPlayer

hasReferrer

methodplugins · game:read

hasReferrer(options?: ActOptions) => Promise<boolean>

Asks whether the player has already named who referred them (sendHasReferralAssociate, refh), as the buddy list does for a new account.

Parameters

Name	Type
options optional	ActOptions

Returns

Promise<boolean>

Types

ActOptions

knownCode

methodplugins · game:read

knownCode() => Promise<ReferralCode | null>

The code the client's refer a friend popup fetched this sitting (ReferAFriend.code), or null.

Returns

Promise<ReferralCode \| null>

Types

ReferralCode

list

methodplugins · game:read

list(options?: ReferralPageOptions) => Promise<ReferralPage>

A page of the players who joined with the player's code (sendReferralReferralsRequest, refr), page 1 first in pages of 8, as the "my referrals" panel asks. Throws REFUSED when the server refuses the page.

Parameters

Name	Type
options optional	ReferralPageOptions

Returns

Promise<ReferralPage>

Types

ReferralPageOptions · ReferralPage · ReferredPlayer · Referral

nameReferrer

methodplugins · game:act

nameReferrer(userName: string, options?: ActOptions) => Promise<string>

Names the player who referred this one (sendReferralAssociation, refa), for good, as the "how did you hear about us" popup does. Throws a RangeError for a name under two characters, and REFUSED for the player's own name or when the server does not record it.

Parameters

Name	Type
userName	string
options optional	ActOptions

Returns

Promise<string>

Types

ActOptions

rewards

methodplugins · game:read

rewards() => Promise<ReferralRewards>

The four treasures the refer a friend popup shows, read from the account's two stats.

Returns

Promise<ReferralRewards>

Types

ReferralRewards

Events

onCode

eventplugins · game:read

onCode(listener: (code: ReferralCode | null) => void) => () => void

Hears the referral code arrive, whoever asked; null when the server gave none.

Parameters

Name	Type
listener	(code: ReferralCode | null) => void

Returns

() => void. Call it to stop listening.

Types

ReferralCode

onHasReferrer

eventplugins · game:read

onHasReferrer(listener: (hasReferrer: boolean) => void) => () => void

Hears each answer to whether a referrer is named, whoever asked.

Parameters

Name	Type
listener	(hasReferrer: boolean) => void

Returns

() => void. Call it to stop listening.

onList

eventplugins · game:read

onList(listener: (page: ReferralPage) => void) => () => void

Hears each page of referrals arrive, whoever asked; more is false, the page being unknown.

Parameters

Name	Type
listener	(page: ReferralPage) => void

Returns

() => void. Call it to stop listening.

Types

ReferralPage

onReferrerNamed

eventplugins · game:read

onReferrerNamed(listener: (refusal: string | null) => void) => () => void

Hears each answer to naming a referrer, whoever named them: null when recorded, else why not.

Parameters

Name	Type
listener	(refusal: string | null) => void

Returns

() => void. Call it to stop listening.

onRewards

eventplugins · game:read

onRewards(listener: (rewards: ReferralRewards) => void) => () => void

Hears a referral treasure open, with the rewards as they stand after.

Parameters

Name	Type
listener	(rewards: ReferralRewards) => void

Returns

() => void. Call it to stop listening.

Types

ReferralRewards

Types

The types the calls above take and give, with every field. Import any of them in a plugin from @phantomclient/plugin/sdk, or use them as they are in a script.

ActOptions

How long something that acts may take, and what may end it first.

Field	Type
timeoutMs optional	number | undefined	10 seconds by default.
signal optional	AbortSignal | undefined

ReferralCode

The player's referral code, and the link the popup copies for it.

Field	Type
code	string
link	string	https://buddy.animaljam.com/<code>.

ReferralPageOptions

Which page of referrals, and how many make one.

type ReferralPageOptions = ActOptions & { page?: number; pageSize?: number }

ReferralPage

A page of the players who joined with the player's code.

Field	Type
referrals	ReferredPlayer[]
more	boolean	Whether there may be more to ask for, as the panel decides: it asks again while the answer holds at least page * pageSize players. False when heard without knowing what was asked.

ReferredPlayer

A player who joined with the player's code.

type ReferredPlayer = Referral & {
  /** Whether the client counts them a member: any account type but `Non-Member`. */
  member: boolean;
}

Referral

A player who joined with the player's code, as the referrals list describes one.

Field	Type
userName	string	Their username (name).
moderatedUserName	string | null	The name to show for them (moderatedUserName), as the server sent it; null when it sent none, which the client shows as its stock name (translation 11098).
nameBarData	number | null	Their name bar (namebarData); null when the server sent none, which the client reads as 0.
accountType	string	Their account type as the server words it (account_type). The client counts anything but Non-Member as a member.

ReferralRewards

How far along the refer a friend rewards the player is, as the popup shows them.

Field	Type
treasures	boolean[]	The four treasures above the popup's progress bar, in its order; true for an opened one.
opened	number	How many are open, which is how far the bar is filled.