Developer Guide



Developer GuideSDKTable of Contents TOC \o "1-2" Overview PAGEREF _Toc510790058 \h 3Setting Pre-Population Values PAGEREF _Toc510790059 \h 3Intended Audience PAGEREF _Toc510790060 \h 3Android PAGEREF _Toc510790061 \h 4Not Passing in the Locale, Resuming to Subsequent Activity, Request Code = 1 PAGEREF _Toc510790062 \h 5Passing in the Locale, Resuming to Subsequent Activity, Request Code = 2 PAGEREF _Toc510790063 \h 5Passing in the Locale, staying on same activity, request code = 5 PAGEREF _Toc510790064 \h 5iOS PAGEREF _Toc510790065 \h 7Not Passing in the Locale, Resuming to Subsequent Controller8Passing in the Locale, Resuming to Subsequent Controller8Passing in the Locale, staying on Same Controller8Flow Chart10OverviewThis document outlines how to use the MaritzCX Mobile SDK, for both the Android and iOS platforms. It allows a survey to be presented to a user at the following times:When a user logs in.When a user logs out.When a user visits a screen.When a user visits a screen and does nothing.When a user exits a screen four times.Notes: 1. This list is not exhaustive. 2. There is an administrative tool used by our Implementation team members to define, for a given program, which surveys will be presented at which times.For each of these scenarios, an event alias must be defined, such as user_logs_in, user_logs_out, etc. Within a given program, there may be many surveys. These rules are definable at the survey level. The developer must include the respective SDK into their pre-existing app. The SDK provides a configurable object and method call to reach into the SDK to present a survey (or not), depending upon the rules defined in the aforementioned administration interface. The developer must inform the SDK of the following values, so that the rules can be executed properly:Locale (e.g. en-us, fr-ca, etc.) - This will be determined automatically if the developer has not indicated it.Program Token - This is given to the developer by the business owner or manager.Event Alias - This is the required alias for informing the SDK of which rules to execute.The SDK supports the conditional presentation of a survey. It will also support passing forward to the next screen or remaining on the existing screen. This capability is essential for when an event is triggered that the user expects to produce a result. When the survey is completed and the user exits it, they may proceed as expected.It is critical that the event aliases are shared and coordinated.Setting Pre-Population ValuesSome surveys require that either the survey populate with something (typically about the user) or pass values behind-the-scenes. The SDK requires that you pass these values in by deriving them within the application. This will require that the business owner/manager and the developer agree on the list of named values to be passed in. Then, the developer calls a method for each named value and passes both the name and the value before launching the survey.Intended AudienceThe intended audience for this document is both the developer who is integrating the SDK into their pre-existing mobile and the business owner or manager who is defining the rules for survey presentation.AndroidHere are the steps necessary to integrate the in-app survey Android SDK (henceforth referred to as the In-App Survey Module):1.Download the .aar file.2.Open your existing application in Android Studio.3.Perform the following steps.a.Add “New Module”.b.Choose “Import .JAR/.AAR File”.c.Choose the file.d.It should prefill the Project Name with “InAppSurvey”. If not, name it as such.4.Change your module-specific gradle file to include the following in the dependencies section.pile project(':InAppSurveyModule')pile 'com.google.code.gson:gson:2.2.4'pile 'com.squareup.okhttp3:okhttp:3.4.2'5.Ensure that the module in which you’re using the In-App Survey Module includes the module provided. a.Right-click on the module where you’re intending to use it and choose “Open Module Settings”. b.Choose the module, choose the “Dependencies” tab. c.Choose the plus sign. d.Choose “3. Module dependency”. e.Choose the In-App Survey Module.6.To inject a potentially-displayed survey, do two things:a.Add the necessary imports:i.import com.maritzcx.inappsurvey.SurveyPresentation.Models.RuleRequestModel;ii. import com.maritzcx.inappsurvey.SurveyPresentation.Presenter; b.Add the call to possibly present the survey to the user. Here are examples:Not Passing in the Locale, Resuming to Subsequent Activity, Request Code = 1RuleRequestModel aRuleRequestModel = new RuleRequestModel("19283", "user_viewed_account_details",1, null);Presenter aPresenter = Presenter.getInstance();aPresenter.initiateSurvey(this, aRuleRequestModel, new Intent(this, ThirdActivity.class));Passing in the Locale, Resuming to Subsequent Activity, Request Code = 2Locale aLocale = this.getResources().getConfiguration().locale;RuleRequestModel aRuleRequestModel = new RuleRequestModel("19283", "user_viewed_notifications",2, aLocale);Presenter aPresenter = Presenter.getInstance();aPresenter.initiateSurvey(this, aRuleRequestModel, new Intent(this, ThirdActivity.class));Passing in the Locale, staying on same activity, request code = 5Presenter aPresenter = Presenter.getInstance();Locale aLocale = this.getResources().getConfiguration().locale;RuleRequestModel aRuleRequestModel = new RuleRequestModel("19283", "clicked_logout",5, aLocale);aPresenter.initiateSurveyAndFinish(this, aRuleRequestModel);So, what is the call doing? You create a model and provide the In-App Survey Module some details. They are:The optional locale.The program token; provided to you by your business owner or manager.The event alias. This is an agreed-upon value between you and your business owner/manager. It’s the way you indicate the context of the user (just hit a button, landed on a screen, etc.).A request code. This is used to identify, later, which call was made. Using the onActivityResult() method, the developer must check for that value and determine what to do when the survey is completed. Here is an example: @Overrideprotected void onActivityResult(int requestCode, int resultCode, Intent data) {switch (requestCode) {case 1: startActivity(new Intent(this, ThirdActivity.class));break;case 2: startActivity(new Intent(this, ThirdActivity.class));break;case 3: startActivity(new Intent(this, ThirdActivity.class));break;case 4: startActivity(new Intent(this, ThirdActivity.class));break;case 5: finish();break;}}Then, you’re passing off control to the In-App Survey Module. You may or may not pass in the Activity that you would for the user to land on, once the survey is completed. There are multiple constructors for this.Do you need to pass in agreed-upon [the MaritzCX implementation team and client app implementation team must agree upon the naming convention] survey prefill values? If so, do this to the RuleRequestModel() instance before calling the initiateSurveyAndFinish() or the initiateSurvey() methods.aRuleRequestModel.addPrePopulationData("<namedfield>", "<namedfieldvalue>");Execute this method for each name/value that you wish to prefill.iOSHere are the steps necessary to integrate the in-app survey iOS SDK (henceforth referred to as the In-App Survey Module):1.With your project open, drag the provided framework file into the project navigator.2.The options for adding these files will appear. Ensure that “Copy items if needed” is checked and click Finish.3.Drag the framework file in the project navigator to the Embedded Binaries section of the target. This is located by clicking on the target and the General tab. If a duplicate entry appears in the Linked Frameworks and Libraries, it can be deleted.4.To inject a potentially-displayed survey, do two things:a.Add the necessary import:i.import InAppFrameworkb.Add the call to possibly present the survey to the user. Here are examples:Not Passing in the Locale, Resuming to Subsequent Controllerlet myRuleRequestModel = RuleRequestModel() myRuleRequestModel.programtoken = "program_token" myRuleRequestModel.eventalias = "event_alias" let myPresenter = Presenter() myPresenter.initiateSurvey(currentController: self, ruleRequestModel: myRuleRequestModel, nextController: "SecondViewController")Passing in the Locale, Resuming to Subsequent Controllerlet myRuleRequestModel = RuleRequestModel() myRuleRequestModel.programtoken = "program_token" myRuleRequestModel.eventalias = "event_alias" let aLocale = Locale.current myRuleRequestModel.localeobject = aLocale let myPresenter = Presenter() myPresenter.initiateSurvey(currentController: self, ruleRequestModel: myRuleRequestModel, nextController: "SecondViewController")Passing in the Locale, staying on same controllerlet myRuleRequestModel = RuleRequestModel() myRuleRequestModel.programtoken = "program_token" myRuleRequestModel.eventalias = "event_alias" let aLocale = Locale.current //manipulate this, as you see fit myRuleRequestModel.localeobject = aLocale let myPresenter = Presenter() myPresenter.initiateSurvey(currentController: self, ruleRequestModel: myRuleRequestModel, nextController: nil)So, what is the call doing? You create a model and provide the In-App Survey SDK some details. They are:The optional locale.The program token; provided to you by your business owner or manager.The event alias. This is an agreed-upon value between you and your business owner/manager. It’s the way you indicate the context of the user (just hit a button, landed on a screen, etc.).Then, you’re passing off control to the In-App Survey SDK. You may or may not pass in the Controller that you would for the user to land on, once the survey is completed.Do you need to pass in agreed-upon [the MaritzCX implementation team and client app implementation team must agree upon a naming convention] survey prefill values? If so, do this to the RuleRequestModel() instance before calling the initiateSurvey() method.myRuleRequestModel.addPrePopulationData(namedField: "firstname", namedFieldValue: "Eduardo")Execute this method for each name/value that you wish to prefill.Flowchart129540-3175Flowchart DefinitionsProgram Token - naming convention for individual app deployment (any number of events and or surveys can be run within a single program token)ExampleMCXMOBILE_CLIENTNAME_CUSTOMERSAT?Event – measured behavior on the part of the app user Exampleuser_logs_inRule – sequence of events that result in an invitation prompt; rules determine when and where invitations are displayedExampleUse event ‘user_logs_in’ and display invitation prompt on screen two after user has performed specified event three times?Prompt - text to be displayed within the invitationExampleDo you have a minute to provide feedback on XYZ app? Your feedback will help us improve the features and functionality provided through the app’ Yes / NoSurvey - URL to a web survey programmed within the MaritzCX Survey BuilderExample ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download