IR Campaign Screen Launch

This section will help you to understand how to launch the campaign screen or the login screen in your app using the InviteReferrals SDK.

Use the code mentioned below in order to activate the referral screen: -

InviteReferralsApi.getInstance(activityContext).campaign(IRUserData.Builder userInfo, IRCampaignData.Builder campaignInfo, OnUIBuild onUIBuild)
InviteReferralsApi.getInstance(activityContext).campaign(IRUserData.Builder userInfo, IRCampaignData.Builder campaignInfo, OnUIBuild onUIBuild)

Parameters

The parameters used in the above function are as follows: -

ParameterDescriptionValue
setUserName (string)customer's nameabc
setUserEmail (string)customer's email id[email protected]
setUserMobile (string)customer's mobile number9812XXXXXX
setCustomValueOne (string)Any extra value you wanted to receiveMumbai
setCustomValueTwo (string)Any extra value you wanted to receiveMaharashtra
setCampaignID (int)ID of the campaign10XXX
setTemplateID (int)ID of the UI template0 (for default UI) or 1

When you call the above method in your app, then this function either loads the login screen or the campaign screen according to the value you have passed.

Login Screen

This screen will get loaded in case you don't pass user data in the function as shown in the example mentioned below: -

IRCampaignData.Builder campaignInfo = new IRCampaignData.Builder();
campaignInfo.setCampaignID(0);
campaignInfo.setTemplateID(1);
campaignInfo.build();

InviteReferralsApi.getInstance(activityContext).campaign(null, campaignInfo, new OnUIBuild() {
   @Override
   public void onCampaignScreen(JSONObject response) {
       //do your task here
   }

   @Override
   public void onShareIconClick(JSONObject data) {
       //do your task here
   }

   @Override
   public void onCloseButtonClick() {
       //do your task here
   }

   @Override
   public void onCaptureLeadFormSubmission(JSONObject response) {
       //do your task here
   }
});
val campData = IRCampaignData.Builder();
campData.setCampaignID(0);
campData.setTemplateID(1);
campData.build();

InviteReferralsApi.getInstance(activityContext).campaign(null, campData, object: OnUIBuild {
    override fun onCampaignScreen(p0: JSONObject?) {
        //do your task here
    }

    override fun onShareIconClick(p0: JSONObject?) {
        //do your task here
    }

    override fun onCloseButtonClick() {
        //do your task here
    }

    override fun onCaptureLeadFormSubmission(p0: JSONObject?) {
        //do your task here
    }
})

You will get the following screen as an output (screenshot provided below). It's the default UI of the login screen of InviteReferrals Android SDK.

311

Some parts of the UI are customizable like the heading’s text, the heading’s color, the image of the cross-shaped button etc. Here all customizations are done from the various resource files like strings.xml or integers.xml, etc. For further information refer to the section titled ‘Campaign Screen UI Customization(s) & Other Configurations’.

If you want to change the content of the login page, then you can change it from the IR dashboard.
Go to Campaigns → Open Referral Portal Section from Options Menu → Login Screen. From here you can change the content as per your requirements and update it. Your updated content will reflect from the next app launch onwards.

📘

REMEMBER

Within the login screen, the Name & Email Address fields are mandatory fields. You can also opt to add the Mobile Number field as per your requirement from the Login Screen section in the IR dashboard.

Campaign Screen

This screen will get loaded in case you pass user data in the function as shown in the example provided below. The sharing screen appears once the user logins into the REFERRAL campaign. The screen enables the user to refer the brand to his/her friends or acquaintances so that he/she can earn points and rewards for referring.

IRUserData.Builder userInfo = new IRUserData.Builder();
userInfo.setUserName(“abc”);
userInfo.setUserEmail(“[email protected]”);
userInfo.setUserMobile(“9999999999”);
userInfo.setCustomValueOne(“custom_val_1”);
userInfo.setCustomValueTwo(“custom_val_2”);
userInfo.build();

IRCampaignData.Builder campaignInfo = new IRCampaignData.Builder();
campaignInfo.setCampaignID(0);
campaignInfo.setTemplateID(0);
campaignInfo.build();

InviteReferralsApi.getInstance(activityContext).campaign(userInfo, campaignInfo, new OnUIBuild() {
       @Override
       public void onCampaignScreen(JSONObject response) {
           //do your task here
       }

       @Override
       public void onShareIconClick(JSONObject data) {
           //do your task here
       }

       @Override
       public void onCloseButtonClick() {
           //do your task here
       }

       @Override
       public void onCaptureLeadFormSubmission(JSONObject response) {
           //do your task here
       }
   });
});
val userData = IRUserData.Builder();
userData.setUserName("abc");
userData.setUserEmail("[email protected]");
userData.setUserMobile("9999999999");
userData.setCustomValueOne("custom_val_1");
userData.setCustomValueTwo("custom_val_2");
userData.build();

val campData = IRCampaignData.Builder();
campData.setCampaignID(0);
campData.setTemplateID(0);
campData.build();

InviteReferralsApi.getInstance(activityContext).campaign(userData, campData, object: OnUIBuild {
    override fun onCampaignScreen(p0: JSONObject?) {
        //do your task here
    }

    override fun onShareIconClick(p0: JSONObject?) {
        //do your task here
    }

    override fun onCloseButtonClick() {
        //do your task here
    }

    override fun onCaptureLeadFormSubmission(p0: JSONObject?) {
        //do your task here
    }
})

Different types of layouts or template variants are available for the campaign screen and each layout has its own distinct design or output.

Some parts of the UI are customizable like the size of the icons, colour of the text etc. Here all customizations are done from the various resource files such as strings.xml, integers.xml etc. For further information refer to the section titled ‘Campaign Screen UI Customization(s) & Other Configurations’.

If you want to change the content of the campaign page, then you can do so from the IR dashboard.
Go to Campaigns → Open Referral Portal Section from Options Menu → Sharing Screen. From here you can change the content as per your requirements and update it. Your updated content will reflect from the next app launch onwards.

Templates In Campaign Screen

Currently we have 2 templates for the campaign screen in IR SDK. For Template1, you need to pass templateID as 0 in the function. And for Template2, you need to pass templateID as 1 in the function. These templates for the campaign screen can be customized.

📘

NOTE

By default, the value will be 0.

Template 1 [Default UI]

1283

Template 2

304

Callback Response

The function described above will provide you with 4 different callbacks. Their responses are as follows: -

1. onCampaignScreen()
This function will provide you a response whenever the campaign screen’s loading process starts.

{
   "status":"success",
   "message":"Campaign UI <LOGIN> successfully loaded.",
   "type":"_1_0"
}

The messages that you receive in this function are as follows: -

StatusMessageTypeDescription
successCampaign UI successfully loaded.

Campaign UI successfully loaded.
_1_1


_1_0
When the IR campaign screen successfully launches the login UI.
When the IR campaign screen successfully launches the sharing UI.
failData not found






Campaign data not found




Campaign data not found






Something went wrong with the following error →








Something went wrong while fetching campaignID.



Something went wrong while parsing with the following error →


Something went wrong with error →



CAMPAIGNID = ; Campaign is Inactive.


Campaign id is invalid




Parameter missing in response from user details.
_2_0

_2_1

_2_3


_2_2




_3_0

_3_1

_3_2


_4_0

_4_2

_4_4

_4_5

_4_6


_4_1




_4_3




_4_7




_5_0

_5_1


_6_0




_7_0

_7_1
When there is no campaign data & user data available in the IR-SDK.




When campaign data is not passed in the campaign() function.


When campaign data is not available.





When any exception occurred while reading campaign data from the file in the IR-SDK.








Any error occurred while retrieving campaignID internally.


Any error occurred while parsing campaign data internally.


When any exception occurred while checking data passed in the campaign() function.


When a campaign is inactive from the IR dashboard.



When a campaign id passed in the campaign() function is invalid.


When user stats are found missing.

2. onShareIconClick()
This function will provide you with a response whenever any custom share icon is clicked on the sharing screen.

{
   "source":"More Share Option"
}

The messages that you receive as source in this function, are as follows: -

Source
More Share Option
WhatsApp
Gmail
Contact Sync
Facebook
Facebook Messenger
Twitter
LinkedIn
Pinterest
SMS
Telegram

3. onCloseButtonClick()
This function will not provide you any response. It will only be triggered & give you the hit on the click of the close button on the campaign screen.

4. onCaptureLeadFormSubmission()
This function will provide you with a response whenever the user fills the capture lead form on the sharing screen (templateID as 0).

{
   "status":"fail",
   "message":"Incorrect EmailID or Mobile Number"
}

The messages you receive in this function are as follows: -

StatusMessageDescription
successLead Capturing is SuccessfulWhen data is sent to the server successfully.
failIncorrect EmailID or Mobile Number



Lead Capturing is Failed


Something Went Wrong


When the user passes the wrong format of email id or mobile number.


If the response from API fails.


If no response is received from API.


If any exception occurred while sending a request to the server.

Inactive Campaign Screen

This screen is activated only when the following conditions are satisfied: -
a. Campaign’s status must be set to ‘Inactive’ in the IR dashboard.
b. Inactive Campaign Content must be entered for the campaign within its corresponding editor section (screenshot attached below).

1762

In case your campaign is set to 'Inactive' in the IR dashboard, yet you try to launch the campaign screen: -

  • With content in the dashboard → then → the inactive campaign screen will be launched (sample screenshot attached below for reference).
289
  • Without content in the dashboard → then → this will show you a toast with the following message “Something Went Wrong”.

Referral Statistics

This section is used to show the referral stats of the current user. In the campaign sharing screen, you will notice that there is a button titled “My Referral Statistics”. If you click on this button, a dialog box mentioning the user’s stats would appear on-screen. (screenshot attached)

1555

The availability of the ‘My Referral Statistics’ button on the sharing screen can be switched ON/OFF from within the IR dashboard. If you don't want to show this button on the sharing screen, then you can untick the checkbox titled ‘Show Referral Statistics’ in the IR dashboard. Find this option at Your campaign → Referral Portal → Settings.

1577

Terms & Conditions

This section is used to show the terms & conditions regarding the referral of your app to the current user. In the campaign sharing / login screen, you would notice that there exists a button titled ‘Terms & Conditions’. If you click on this button, a dialog box would appear on-screen displaying your ‘terms & conditions’ content. (screenshot attached)

1631

In the panel, you can enter the content at Your Campaign → Referral Portal → Settings → Bottom of the Page. If no content is available in the editor then by default Terms & Conditions button will not be displayed on the campaign screen in the app.

1505

How It Works

This section outlines the functioning of the ‘How It Works’ section that is available on the screen titled ‘Refer and Earn’ which in turn gets displayed when you refer your app to any prospective user. In the campaign sharing / login screen, you would notice that there exists a button titled ‘How It Works’. If you click on this button, a dialog box would appear on-screen displaying your ‘How It Works’ content (screenshot attached below).

1547

In the panel, you can enter the content at Your Campaign → Referral Portal → Settings → Middle of the Page. If no content is available in the editor, then the ‘How It Works’ button will not be displayed by default on the campaign screen within the app.

1592

Show Refer A Friend Widget

Simply, add the following line of code in the activity in which you want to show the referral program widget.

InviteReferralsApi.getInstance(activityContext).campaignPopup(String ruleName, IRUserData.Builder userInfo, IRCampaignData.Builder campInfo);
InviteReferralsApi.getInstance(activityContext).campaignPopup(String ruleName, IRUserData.Builder userInfo, IRCampaignData.Builder campInfo);

Parameters

Following are the parameters used in the function mentioned above: -

ParameterDescriptionValue
ruleName (string)Name of the rule to activate popuphome
setUserName (string)customer's nameabc
setUserEmail (string)customer's email id[email protected]
setUserMobile (string)customer's mobile number9812XXXXXX
setCustomValueOne (string)Any extra value you wanted to receivemumbai
setCustomValueTwo (string)Any extra value you wanted to receivemaharashtra
setCampaignID (int)ID of the campaign10XXX
setTemplateID (int)ID of the UI template0 (for default UI) or 1

To activate the widget, you need to call the function mentioned above as depicted in the following example: -

IRUserData.Builder userInfo = new IRUserData.Builder();
userInfo.setUserName(“abc”);
userInfo.setUserEmail(“[email protected]”);
userInfo.setUserMobile(“9090909090”);
userInfo.setCustomValueOne(null);
userInfo.setCustomValueTwo(null);
userInfo.build();

IRCampaignData.Builder campaignInfo = new IRCampaignData.Builder();
campaignInfo.setCampaignID(123);
campaignInfo.setTemplateID(1);
campaignInfo.build();

InviteReferralsApi.getInstance(activityContext).campaignPopup("home", userInfo, campaignInfo);
val campaignInfo = IRCampaignData.Builder();
campaignInfo.setCampaignID(123);
campaignInfo.setTemplateID(1);
campaignInfo.build();

val userInfo = IRUserData.Builder();
userInfo.setUserName("abc");
userInfo.setUserEmail("[email protected]");
userInfo.setUserMobile("9090909090");
userInfo.setCustomValueOne(null);
userInfo.setCustomValueTwo(null);
userInfo.build();

InviteReferralsApi.getInstance(activityContext).campaignPopup("home", userInfo, campaignInfo);

📘

NOTE

RuleName will be checked against campaignID.

  • If user data is not passed in the function then the widget will redirect to the IR login screen.
  • If campaign data is not passed in the function then the widget will not work & the following log will be printed “No Campaign Data passed from the function.”;
  • Rule Name & corresponding campaignID is required.

The widget will display the content you have passed in the Login Screen Editor section in the IR dashboard. (screenshot attached)

273

In the IR dashboard you can configure rules at Your Campaign → Integration → Mobile App.

1677

Clear User Details

If you want to clear user data from the IR-SDK, then you can call the function mentioned below: -

InviteReferralsApi.getInstance(activityContext).clearUserDetails();
InviteReferralsApi.getInstance(activityContext).clearUserDetails()

By default, SDK automatically clears all user data on every app launch.

Create Your Own Campaign Screen

This function can be used, in case you want to design your own custom campaign screen, using our campaign data.

IRUserData.Builder userInfo = new IRUserData.Builder();
userInfo.setUserName(name);
userInfo.setUserEmail(email);
userInfo.setUserMobile(mobile);
userInfo.setCustomValueOne(null);
userInfo.setCustomValueTwo(null);
userInfo.build();

IRCampaignData.Builder campaignInfo = new IRCampaignData.Builder();
campaignInfo.setCampaignID(campaignID);
campaignInfo.setTemplateID(0);
campaignInfo.build();

InviteReferralsApi.getInstance(activityContext).getSharingDetails(new InviteReferralsSharingInterface() {
   @Override
   public void getShareData(JSONObject sharingDetails) {
       //do your task here
   }
}, userInfo, campaignInfo);
val userData = IRUserData.Builder();
userData.setUserName(name);
userData.setUserEmail(email);
userData.setUserMobile(mobile);
userData.setCustomValueOne(null);
userData.setCustomValueTwo(null);
userData.build();

val campaignInfo = IRCampaignData.Builder();
campaignInfo.setCampaignID(campaignID);
campaignInfo.setTemplateID(0);
campaignInfo.build();

InviteReferralsApi.getInstance(activityContext).getSharingDetails(object : InviteReferralsSharingInterface {
     override fun getShareData(p0: JSONObject?) {
         //do your task here
     }
}, userData, campaignInfo)

📘

NOTE

If you don't pass user data then this callback will provide you with only the campaign-related data. However, if you pass user data then it will provide all data i.e. campaign data along with the user data.

Response with User Data

{
   "Authentication":"success",
   "CustomerName":"Jack90",
   "Email":"[email protected]",
   "referral_code":"JACK",
   "referral_link":"https:\/\/tagnpinyA.talentfizz.com\/c\/i\/200\/972",
   "unique_code":"",
   "stats":{
      "totalInvites":"8",
      "totalClicks":"234",
      "totalConverts":"0"
   },
   "campaignID":200,
   "popup_shareText":"https:\/\/tagnpinyA.talentfizz.com\/c\/i\/200\/972 Refer and win #Referral #Contests #inviteReferrals",
   "shareSubject":"Explore Tagnpin Referral Contest",
   "inviteMail":"Hi, Your friend Jack90, has invited you to try Tagnpin through his referral link.\nAccept the invitation by clicking the link mentioned below.\nhttps:\/\/tagnpinyA.talentfizz.com\/c\/i\/200\/972",
   "twitter_share_text":"https:\/\/tagnpinyA.talentfizz.com\/c\/i\/200\/972 Refer and win #Referral #Contests #inviteReferrals",
   "email_shareText":"Hi, Your friend Jack90, has invited you to try Tagnpin through his referral link.\nAccept the invitation by clicking the link mentioned below.\nhttps:\/\/tagnpinyA.talentfizz.com\/c\/i\/200\/972",
   "whatsapp_shareText":"Refer and win #Referral #Contests #inviteReferrals https:\/\/tagnpinyA.talentfizz.com\/c\/i\/200\/972",
   "sms_shareText":"https:\/\/tagnpinyA.talentfizz.com\/c\/i\/200\/972 Refer and win #Referral #Contests #inviteReferrals",
   "twitter_shareText":"https:\/\/tagnpinyA.talentfizz.com\/c\/i\/200\/972 Refer and win #Referral #Contests #inviteReferrals",
   "linkedin_shareText":"https:\/\/tagnpinyA.talentfizz.com\/c\/i\/200\/972 Refer and win #Referral #Contests #inviteReferrals",
   "pinterest_shareText":"https:\/\/tagnpinyA.talentfizz.com\/c\/i\/200\/972 Refer and win #Referral #Contests #inviteReferrals",
   "fb_shareText":{
      "fbLink":"https:\/\/tagnpinyA.talentfizz.com\/c\/i\/200\/972 Refer and win #Referral #Contests #inviteReferrals",
      "fbImage":"https:\/\/s3.ap-south-1.amazonaws.com\/stage-tagnpin\/images\/fb_49_200.jpg"
   },
   "loginScreenData":"<link rel=\"stylesheet\" href=\"https:\/\/maxcdn.bootstrapcdn.com\/bootstrap\/3.3.5\/css\/bootstrap.min.css\"><style>body{background: transparent;}<\/style><div class=\"text-center\">\n    <h3><br \/>Heading<\/h3>\n    <p class=\"lead\">\n        The description of your referral campaign \n        <br>\n        comes here\n    <\/p>\n<\/div>",
   "shareScreenData":"<link rel=\"stylesheet\" href=\"https:\/\/maxcdn.bootstrapcdn.com\/bootstrap\/3.3.5\/css\/bootstrap.min.css\"><style>body{background: transparent;}<\/style><div class=\"text-center\">\n<h3><br \/>Heading<\/h3>\n<p class=\"lead\">The description of your referral campaign <br \/>comes here<br \/><span style=\"color: #ba372a;\"><strong>I am from Campaign : 200<\/strong><\/span><\/p>\n<\/div>",
   "howItWorks":"<div><img src=\"https:\/\/as2.ftcdn.net\/v2\/jpg\/01\/87\/31\/25\/1000_F_187312561_kMY7AYVLSwCz6Jua7KusMMPQtb4TayFA.jpg\" width=\"500\" height=\"500\" alt=\"\" style=\"display: block; margin-left: auto; margin-right: auto;\" \/><\/div>",
   "tnc":"This is Terms and Conditions section."
}

Response without User Data

{
   "Authentication":"success",
   "campaignID":200,
   "popup_shareText":"{referral link} Refer and win #Referral #Contests #inviteReferrals ",
   "shareSubject":"Explore Tagnpin Referral Contest",
   "inviteMail":"Hi, Your friend {customer name}, has invited you to try Tagnpin through his referral link.\nAccept the invitation by clicking the link mentioned below.\n{referral link}",
   "twitter_share_text":"{referral link} Refer and win #Referral #Contests #inviteReferrals ",
   "email_shareText":"Hi, Your friend {customer name}, has invited you to try Tagnpin through his referral link.\nAccept the invitation by clicking the link mentioned below.\n{referral link}",
   "whatsapp_shareText":"Refer and win #Referral #Contests #inviteReferrals ",
   "sms_shareText":"{referral link} Refer and win #Referral #Contests #inviteReferrals ",
   "twitter_shareText":"{referral link} Refer and win #Referral #Contests #inviteReferrals ",
   "linkedin_shareText":"{referral link} Refer and win #Referral #Contests #inviteReferrals ",
   "pinterest_shareText":"{referral link} Refer and win #Referral #Contests #inviteReferrals ",
   "fb_shareText":{
      "fbLink":"{referral link} Refer and win #Referral #Contests #inviteReferrals ",
      "fbImage":"https:\/\/s3.ap-south-1.amazonaws.com\/stage-tagnpin\/images\/fb_49_200.jpg"
   },
   "loginScreenData":"<link rel=\"stylesheet\" href=\"https:\/\/maxcdn.bootstrapcdn.com\/bootstrap\/3.3.5\/css\/bootstrap.min.css\"><style>body{background: transparent;}<\/style><div class=\"text-center\">\n    <h3><br \/>Heading<\/h3>\n    <p class=\"lead\">\n        The description of your referral campaign \n        <br>\n        comes here\n    <\/p>\n<\/div>",
   "shareScreenData":"<link rel=\"stylesheet\" href=\"https:\/\/maxcdn.bootstrapcdn.com\/bootstrap\/3.3.5\/css\/bootstrap.min.css\"><style>body{background: transparent;}<\/style><div class=\"text-center\">\n<h3><br \/>Heading<\/h3>\n<p class=\"lead\">The description of your referral campaign <br \/>comes here<br \/><span style=\"color: #ba372a;\"><strong>I am from Campaign : 200<\/strong><\/span><\/p>\n<\/div>",
   "howItWorks":"<div><img src=\"https:\/\/as2.ftcdn.net\/v2\/jpg\/01\/87\/31\/25\/1000_F_187312561_kMY7AYVLSwCz6Jua7KusMMPQtb4TayFA.jpg\" width=\"500\" height=\"500\" alt=\"\" style=\"display: block; margin-left: auto; margin-right: auto;\" \/><\/div>",
   "tnc":"This is Terms and Conditions section."
}

Track Invites Manually
Implement this function if you have created your own sharing screen and you want to collect stats in case a customer clicks on any sharing icon.

InviteReferralsApi.getInstance(activityContext).trackInvite(sourceName, campaignID);
InviteReferralsApi.getInstance(activityContext).trackInvite(sourceName, campaignID)
  • ‘sourceName’ parameter will be as per the app name.
  • ‘campaignID’ parameter will be the ID of the campaign against which you want to increase invites.

Below are the details: -

App NameSource Name
Whatsappwhatsapp
GmailEmail
Messengermessenger or fb message
Facebookfacebook or fbshare
Twittertweet or twitter
Linked inlinkedin
SMSsms
Pinterestpinterest
Telegramtelegram
Referral Linkreferral_link_invites_app