Adds a participant to the referral campaign.
Note: A 401
error will be returned if the following conditions are met: (1) the campaign has participant authentication enabled, (2) there is no authentication cookie present on the participant's browser, (3) the given email is the same as an existing participant.
growsurf.addParticipant(data, callback);
Parameter | Data Type | Description |
| String or Object | (Required) A String containing the participant email or an Object containing the participant email and any other data to include for the participant. If providing an Object, any Object keys other than |
| Function | (Optional) A callback function that will be invoked with the added participant data if successful. |
Returns a Promise that resolves with an Object containing limited participant data.
// Email only using a Callbackgrowsurf.addParticipant('gavin@hooli.com', (participant) => {// handle participant});// Object using a Callbackgrowsurf.addParticipant({email: 'gavin@hooli.com',firstName: 'Gavin',lastName: 'Belson',company: 'Hooli, Inc',companySize: 10000}, (participant) => {// handle participant});
// Email only using a Promisegrowsurf.addParticipant('gavin@hooli.com').then(participant => {// handle participant});// Object using a Promisegrowsurf.addParticipant({email: 'gavin@hooli.com',firstName: 'Gavin',lastName: 'Belson',company: 'Hooli, Inc',companySize: 10000}).then(participant => {// handle participant});
{"id": "kafewp","firstName": "Gavin","lastName": "Belson","referralCount": 0,"monthlyReferralCount": 0,"shareUrl": "https://piedpiper.com?grsf=kafewp","rewards": []}
Triggers a referral, awarding referral credit to the referrer of an existing or new participant. If the campaign participant does not exist, they will be newly added.
Note: A 401
error will be returned but the referral will still be triggered if the following conditions are met: (1) the campaign has participant authentication enabled, (2) there is no authentication cookie present on the participant's browser, (3) the given email is the same as an existing participant.
growsurf.triggerReferral(data, callback);
Parameter | Data Type | Description |
| String or Object | (Optional) A String containing the participant email or an Object containing the participant email and any other data to include for the participant. If providing an Object, any Object keys other than *This parameter is only optional if the participant has already signed up for the campaign and GrowSurf is able to determine they are a participant (does not include participants imported or manually added using the dashboard). For more information about metadata please see our API Guidelines. |
| Function | (Optional) A callback function that will be invoked with the added or updated participant data if successful. |
Returns a Promise that resolves with an Object containing limited participant data.
// Email only using a Callbackgrowsurf.triggerReferral('gavin@hooli.com', (participant) => {// handle participant});// Object using a Callbackgrowsurf.triggerReferral({email: 'gavin@hooli.com',firstName: 'Gavin',lastName: 'Belson',company: 'Hooli, Inc',companySize: 10000}, (participant) => {// handle participant});
// Email only using a Promisegrowsurf.triggerReferral('gavin@hooli.com').then(participant => {// handle participant});// Object using a Promisegrowsurf.triggerReferral({email: 'gavin@hooli.com',firstName: 'Gavin',lastName: 'Belson',company: 'Hooli, Inc',companySize: 10000}).then(participant => {// handle participant});
{"id": "kafewp","firstName": "Gavin","lastName": "Belson","referralCount": 0,"shareUrl": "https://piedpiper.com?grsf=kafewp","rewards": []}
Retrieves limited details of a campaign.
growsurf.getCampaign(callback);
Parameter | Data Type | Description |
| Function | (Optional) A callback function that will be invoked with the campaign data. |
Returns a Promise that resolves with an Object containing limited campaign data.
// Using a Callbackgrowsurf.getCampaign((campaign) => {// Handle Campaign});
// Using a Promisegrowsurf.getCampaign().then(campaign => {// Handle Campaign});
{id: "bpsxg4"}
Retrieves limited details of an existing participant. You will need to supply the unique email of the participant.
Note: A 403
error will be returned if the following conditions are met: (1) the campaign has participant authentication enabled, (2) there is no authentication cookie present on the participant's browser.
growsurf.getParticipantByEmail(participantEmail, callback);
Parameter | Data Type | Description |
| String | (Required) The email of the participant to retrieve. |
| Function | (Optional) A callback function that will be invoked with the participant data if successful or |
Returns a Promise that resolves with an Object containing the participant data. If the participant does not exist in the campaign, then undefined
is returned.
// Using a callbackgrowsurf.getParticipantByEmail('gavin@hooli.com', (participant) => {// Handle participant data});
// Using a promisegrowsurf.getParticipantByEmail('gavin@hooli.com').then(participant => {// Handle participant data});
{"id": "kafewp","firstName": "Gavin","lastName": "Belson","referralCount": 0,"monthlyReferralCount": 0,"shareUrl": "https://piedpiper.com?grsf=kafewp","rewards": []}
Retrieves limited details of an existing participant. You will need to supply the GrowSurf unique identifier that was returned upon participant creation.
Note: A 403
error will be returned if the following conditions are met: (1) the campaign has participant authentication enabled, (2) there is no authentication cookie present on the participant's browser.
growsurf.getParticipantById(participantId, callback);
Parameter | Data Type | Description |
| String | (Required) The GrowSurf identifier of the participant to retrieve. |
| Function | (Optional) A callback function that will be invoked with the participant data if successful or |
Returns a Promise that resolves with an Object containing the participant data. If the participant does not exist in the campaign, then undefined
is returned.
// Using a Callbackgrowsurf.getParticipantById('kafewp', (participant) => {// Handle participant data});
// Using a promisegrowsurf.getParticipantById('kafewp').then(participant => {// Handle participant data});
{"id": "kafewp","firstName": "Gavin","lastName": "Belson","referralCount": 0,"monthlyReferralCount": 0,"shareUrl": "https://piedpiper.com?grsf=kafewp","rewards": []}
Returns the ID of the participant that referred the visitor or null
if the visitor was not referred. This method will first check to see if a grsf
URL parameter exists, then will check for the presence of a referrer ID as a browser cookie (which was set from the initial visit).
Example: Someone refers their friend, and the friend visits http://yoursite.com?grsf=1h97da. Calling this method will return 1h97da
(which is the referrer ID).
growsurf.getReferrerId();
growsurf.getReferrerId();
"1h97da"
Returns the ID of the authenticated participant or null
if there is no participant authentication cookie present.
Example: Someone signed up as a participant in your referral program from your website. Calling this method will return aj7auu1
(which is the participant ID).
growsurf.getParticipantId();
growsurf.getParticipantId();
Example response
"aj7auu1"
Logs the participant out of the browser (clear's the participant's GrowSurf browser cookie and local storage).
growsurf.logout();
growsurf.logout();
Initializes or reinitializes the window.growsurf
Object.
The method is useful if you have set participant authentication as required for your campaign and you would like to automatically authenticate your participants after they log in.
growsurf.init(settings);
Example use
// Using a Callbackgrowsurf.init({ email: "participant@email.com", hash: "HASH_VALUE" }, () => {// GrowSurf is Ready});
// Using a promisegrowsurf.init({ email: "participant@email.com", hash: "HASH_VALUE" }).then(() => {// GrowSurf is Ready});
Parameter | Data Type | Description |
| Object | (Optional) The settings GrowSurf should use when initializing or reinitializing.
|
Opens the GrowSurf window.
growsurf.open(callback);
Parameter | Data Type | Description |
| Function | (Optional) A callback function that will be invoked once complete |
Returns a Promise that resolves once complete.
// Using a Callbackgrowsurf.open(function() {// Do something here});
// Using a Promisegrowsurf.open().then(() => {// Do something here});
Closes the GrowSurf window.
growsurf.close(callback);
Parameter | Data Type | Description |
| Function | (Optional) A callback function that will be invoked once complete |
Returns a Promise that resolves once complete.
// Using a Callbackgrowsurf.close(() => {// Do something here});
// Using a Promisegrowsurf.close().then(() => {// Do something here});
Adds an event subscription of the given event type. When an event of the given type occurs, the given callback will be invoked. Below are detailed descriptions of each event type.
growsurf.subscribe(eventType, callback);
Parameter | Data Type | Description |
| String | (Required) The event type to subscribe to. These are the options:
|
| Function | The callback function that will be invoked when the event occurs. |
// Subscribe to a `signup` event typegrowsurf.subscribe('signup', (participant) => {// A participant was added});// Subscribe to a `share` event typegrowsurf.subscribe('share', (data) => {// A participant shared their unique referral url});// Subscribe to a `referral` event typegrowsurf.subscribe('referral', (participant) => {// A participant was referred});// Subscribe to an `invite` event typegrowsurf.subscribe('invite', (participant) => {// A participant sent out an invite});
Dispatched anytime an event happens. The provided callback will be invoked with an Object containing data relevant to the event.
Dispatched anytime an event happens. The provided callback will be invoked with an Object containing data relevant to the event.
The 'signup' Event returns limited data of the newly added participant.
{"id": "kafewp","firstName": "Gavin","lastName": "Belson","referralCount": 0,"shareUrl": "https://piedpiper.com?grsf=kafewp","rewards": []}
The 'share' Event returns limited data of the participant and the share type.
{"participant": {"id": "kafewp","firstName": "Gavin","lastName": "Belson","referralCount": 0,"shareUrl": "https://piedpiper.com?grsf=kafewp","rewards": []},"type": "facebook"}
The 'referral' Event returns limited data of the newly referred participant.
{"id": "kafewp","firstName": "Gavin","lastName": "Belson","referralCount": 0,"shareUrl": "https://piedpiper.com?grsf=kafewp","rewards": []}
The 'invite' Event returns limited data of the participant and the number of invites sent.
{"participant": {"id": "kafewp","firstName": "Gavin","lastName": "Belson","referralCount": 0,"shareUrl": "https://piedpiper.com?grsf=kafewp","rewards": []},"invitesSent": 3}