Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Info

What is it about?

Capture feedback on your website(s) and/or inside your App(s)

This documentation page will help our customers' developer to set up properly the survey(s).

Note: That it is a new feature and needs to be requested and set up via our Customer Success/Support team as a first step.

1. Parameters available

This is a list of parameters available for the survey. Those can be defined by customers and applied during implementation.

Expand
titleType
  1. Modal (pop-up): Positions the widget in the middle of the screen while hiding screen content.

  2. Footer banner (in-web survey only): Positions the widget at the bottom of the screen while still showing the screen content. Two options are available:

    1. The footer can be persistent (footer) or

    2. The user is able to minimize the widget and click back into it at a later point (persistent-footer).

Expand
titleAppearance

Define how you want to design your survey:

  • Primary color: Change the color of the header and primary button background.

  • Header + Primary button text color: Change the color of the text in the header and primary button background.

  • Paragraph text color: Change the color of the text for messages.

  • Rating scale format (for NPS, CES, or CSAT questions)

    • button : Display the rating scale as numbers.

    • circle: Display the rating scale as circles.

    • star: Display the rating scale as stars.

    • emoji: Display the rating scale as emoticons.

Expand
titleFrequency: How often does the survey appear to the end-user?
  • The frequency depends on the user’s action: Did the user close or answer the survey?

    • A period can be configured to show the survey once or multiple times for each action.

    • Numeric value e.g “1” (day) or “once” expected

Examples:

  • "answered": 3, "closed": 8

    • If answered, the survey shows up again after 3 days

    • If closed, the survey shows up again after 8 days

    • "answered": once, "closed": 0

      • After answering the first time, the survey doesn't show up again

      • After closing, the survey will show up again

    • "answered": 0, "closed": once

      • After closing the first time, the survey doesn't show up again

      • After answering, the survey will show up again

  • Setting default: "answered": 1, "closed": 1

  • Note: Cookies are re-set each time changes are made to the SDK. It means the survey will show up again to the end-user.

⚠️ The “close” frequency is not applicable on the “persistent-footer” type.

Expand
titleTriggers: When the survey is showing to the end-user?

Display the survey:

  • After clicking a button manual

  • After the page loads onLoad

    • Automatically open the questionnaire when the page is
      loaded.

  • Delay on the page delay:<number>

    • Delay amount used for automatically triggered after the user has been on the page for the given time in seconds.

  • Scrolling amount scroll:<number> 

    • Example: when the user scrolls to the middle of the page, the pop-up appears

  • When the user is about to abandon the page (in-web survey only) onPageLeave

2. Web & app SDKs - Set up guide

This part is the technical set up guide to help the developers to implement the survey inside the product (website or application)

Expand
titleWeb SDK

Quickstart

  1. A questionnaire is created in the Customer Alliance platform (with a questionnaire ID).

    1. This questionnaire ID is available on CA platform, and is needed for the setup.

    2. It can be shared by the customer directly, or by our customer support team.

    3. Customers developers don’t need access to the CA platform.

  2. Recommended: Notify our customer support team and let them know the domain(s) of the websites you want to use the questionnaire on so we can restrict it’s usage

  3. Include the questionnaire Javascript SDK into your website before the closing body tag:

Code Block
languagehtml
 <html>
    ...
    <body>
        ...
        <script src="https://questionnaire.customer-alliance.com/ca/embedded/sdk.js"></script>
        <script>
            window.customerAllianceQuestionnaireSdk.init({
                // options that are explained further below
            });
        </script>
    </body>
</html>

API Reference

  • window.customerAllianceQuestionnaireSdk.init(params)

Please run this method before making the call to CA.open(), if you want to set-up the SDK.

Parameters

All parameters are optional.

Name
Type
Description

params

object

A collection of initialization parameters that control the setup of the SDK.

questionnaireID

string

Questionnaire ID from the CA portal.

This parameter is only optional if trigger manual is used and can alternatively be passed as argument for the open function in that case.

For others triggers that don’t need a call to the open function the questionnaireID parameter is mandatory here.

type

string

Accepted values are:

  • pop-up

  • footer

  • persistent-footer

This controls the way to show the questionnaire. As a pop-up or footer overlay.

primaryColor

string

Sets color of title bar background and buttons. e.g. #3B62B2 or black

primaryTextColor

string

Sets text color of title bar background and buttons. e.g. white or #FFFFFF

ratingType

string

Accepted values are circle, star or button

  • button (default)

  • circle

  • star

  • emoji

Rating is shown as mentioned by the type.
Note: The rating scale (1-5, 1-7, 1-10, …) is coming from the questionnaire builder inside CA platform.

frequency

string

  • Frequency must be set for 2 sub parameters- ‘answered’ and ‘closed’.  -

    • Answer means that the user has completed the entire survey.

    • Closed  means that the user has has not answered the survey (drop off) 

  • Values must be entered for answered and closed. 

    • frequency { answered: <value>, closed: <value>} 

  • Accepted values can be: 

    • answered: 'once' - after the questionnaire is answered, it won’t be  shown again. 

    • closed: 'once' - after the questionnaire is clsoed, it won’t be  shown again. 

    • answered: 10 after the questionnaire is answered, it won’t be shown  again in 10 days (if the trigger is condition is met). 10 can be replace  with any whole number. The number represents the delay in number of  days 

    • closed: 10 after the questionnaire is closed, it won’t be shown again  in 10 days (if the trigger is condition is met). 10 can be replace with any  whole number. The number represents the delay in number of days 

trigger

string

Accepted values are:

  • onPageLeave

    • Automatically open the questionnaire when the user leaves the page viewport area.

    • Only work on desktop (detects movement of the mouse)

  • onLoad

    • Automatically open the questionnaire when the page is loaded.

  • manual

    • Default value. open() need to be called to show the questionnaire.

  • scroll:<number> 

    • Scroll amount used for automatically triggered after the user  has scrolled given value. The number is the amount of pixels.

  • delay:<number>

    • Delay amount used for automatically triggered after the user  has been on the page for the given time in seconds. The  number is the delay in seconds. 

    • Deprecated trigger value as number. Example: trigger: 500

attributes

object

JSON object with string values.

Custom data that will be associated to any submitted questionnaire result and is visible on our platform.

Example code:

Code Block
languagejs
window.customerAllianceQuestionnaireSdk.init({ 
    type: 'pop-up', 
    primaryColor: '#3B62B2', 
    primaryTextColor: 'white', 
    frequency: {
      answered: 3, 
      closed: 8 
      }, 
    trigger: 'delay:100', 
    ratingType: 'star', 
    questionnaireID: 'some_questionnaire_id', 
    attributes: { 
      key1: 'value1', 
      key2: 'value2' 
    } 
});

  • window.customerAllianceQuestionnaireSdk.open(optionalQuestionnaireId)

Shows the questionnaire as per the configured or default init options.

Name
Type
Description

questionnaireID

string

Questionnaire ID from the CA portal. Optional value only if configured in CA.init().

Example code:

Code Block
languagejs
window.customerAllianceQuestionnaireSdk.open();
// or
window.customerAllianceQuestionnaireSdk.open('some_questionnaire_id')

Note: questionnaireID can be found on the CA platform in this section of the account:

Types of Questionnaire

Pop-up

Shows a button in the footer as shown below: Upon clicking on it, the footer questionnaire is shown and clicking on close within the footer questionnaire shows the footer button again

Expand
titleIOS SDK

Introduction

CustomerAllianceQuestionnaireis a framework to show survey questionnaires powered by Customer Alliance.

Quickstart

This version is Swift 5 compatible and the minimum OS version required is iOS13

  • CocoaPods

CASurvey is available through CocoaPods. Simply add the following to your Podfile:

Code Block
use_frameworks! 
target '<Your Target Name>'
pod 'CustomerAllianceQuestionnaire'
  • SPM

Select File ▸ Swift Packages ▸ Add Package Dependency…. Paste the Git Repository URL => https://github.com/customer-alliance/questionnaire-ios-sdk . Click Next.

Depending on your GitHub settings, you may need to authenticate your SSH key here. Then, under Rules, make sure Up to Next Major is selected for the version 1.0.0. Click Next.

  • Manually

If you prefer not to use either of the above mentioned dependency managers, you can integrate CustomerAllianceQuestionnaire framework into your project manually. Get the xcframework zip from the team. Drag XCFramework to the Frameworks, Libraries and Embedded Content section of your project target

Usage

CustomerAllianceQuestionnaire exposes CASurveyManager struct which contains all the required methods to show the questionnaire.

Configuration

CustomerAllianceQuestionnaire exposes CASurveyManager struct which contains all the required methods to show the questionnaire. Configuration

configure is a method available inside the CASurveyManager which needs to be called before showing the survey, preferably inside

Parameters

Name
Description
Default value

primaryColor

General theme color used inside the questionnaire popup

#3B62B2

headerAndTitleColor

This is primary text color

White

paragraphTextColor

Color of text used in paragraphs

#586370

ratingStyle

.rectangle, .circle, .star as possible option to define what kind of UI needed in rating questions

.rectangle

frequecyToSubmitForGiven Hash

.answeredClosed(["answered": numeric or numeric value in string or "once", "closed": numeric or numeric value in string or "once”]) as possible options to set whether to show questionnaire with same hash once or multiple times

Deprecated

  • frequecyToSubmitForGivenHash(.one)

  • frequecyToSubmitForGivenHash(.infinite)

.answeredClosed(["answered": 1, "closed": 1])

PreferredLocale

Language locale for survey questionnaire

en

Example

Code Block
import CustomerAllianceQuestionnaire
 func application(_ application: UIApplication, 
didFinishLaunchingWithOptions launchOptions: [UIApplication.
LaunchOptionsKey: Any]?) -> Bool {
 
    // Override point for customization after application launch.
 
    CASurveyManager.sharedManager.configure(headerAndTitleColor: .
white, shouldShowFooter: true, ratingStyle: .rectangle)

    return true
 
  }
 func application(_ application: UIApplication, 
didFinishLaunchingWithOptions launchOptions: [UIApplication.
LaunchOptionsKey: Any]?) -> Bool {

    // Override point for customization after application 
launch. 
    CASurveyManager.sharedManager.configure(headerAndTitleColor: .
white, shouldShowFooter: false, ratingStyle: .rectangle, 
frequecyToSubmitForGivenHash: .infinite)

    return true
  }

Questionnaire Trigger

Code Block
import CustomerAllianceQuestionnaire
 public func showSurveyPopUp(vc:UIViewController, withHash hash:String, 
attributes: [String: Any]? = [:])

showSurveyPopUp method needs to be called whenever the questionnaire needs to be shown on the app.

Parameters: vc -> The view controller in which the pop up needs to be shown

hash - The questionnaire hash

attributes - It is an optional parameter. If user wants to pass additional information in the SDK , he can do it using attributes parameter

Example

Code Block
import UIKit

import CustomerAllianceQuestionnaire

class ViewController: UIViewController {
    override func viewDidLoad() {
      super.viewDidLoad()
      
       // Do any additional setup after loading the view.
     } 
     
    @IBAction func showModalFeedbackVC(_ sender: UIButton) 
{ 
    CASurveyManager.sharedManager.showSurveyPopUp(vc: self, withHash: 
"akjnajjbap6rfjzy6kyvuutn6l2lbsc7dqw4ivama1vvxirq", attributes: [“key“: 
“1234“])
    } 
  }

Note: questionnaire hash can be found on the CA platform in this section of the account:

Expand
titleAndroid SDK

Introduction 

CustomerAllianceFeedback is a library to show survey questionnaires powered by Customer Alliance. 

Installation 

This version is Java 8 compatible and the minimum SDK version required is Android 23. 

Usage 

Please refer to https://search.maven.org/artifact/com.customer-alliance/questionnaire-sdk/1.1/aar

E.g. usage in gradle project with build.gradle

implementation 'com.customer-alliance:questionnaire-sdk:1.1'

CustomerAllianceQuestionFeedback contains CustomerAllianceFeedback class which contains all the required methods to show the questionnaire. Implement the initialize method as follows:

Code Block
Button launch = findViewById(R.id.launch_btn); 
  launch.setOnClickListener(view -> { CustomerAllianceFeedback 
customerAllianceFeedback = new CustomerAllianceFeedback(launcher.this, 
"akjnajjbap6rfjzy6kyvuutn6l2lbsc7dqw4iva ma1vvxirq");
  customerAllianceFeedback.initialize(new IFeedbackInitialization() { 
  @Override 
  public void onSuccess() { 
    customerAllianceFeedback.setHeaderColor("#FFFFFF");
    customerAllianceFeedback.setPrimaryColor("#FF0000");
    customerAllianceFeedback.setShowFooter(true); 
    customerAllianceFeedback.startFeedback(); 
  } 

  @Override 
  public void onFailure() { 
  } 
  })

or

Code Block
Button launch = findViewById(R.id.launch_btn); 
launch.setOnClickListener(view -> { CustomerAllianceFeedback customerAllianceFeedback = new
CustomerAllianceFeedback(launcher.this, "akjnajjbap6rfjzy6kyvuutn6l2lbsc7dqw4iva ma1vvxirq", "en"); 
customerAllianceFeedback.initialize(new IFeedbackInitialization() { 
@Override public void onSuccess() { 
  customerAllianceFeedback.setHeaderColor("#FFFFFF");
  customerAllianceFeedback.setPrimaryColor("#FF0000");
  customerAllianceFeedback.setShowFooter(true); 
  customerAllianceFeedback.setFrequency(3,3); 
  customerAllianceFeedback.startFeedback(); 
} 

@Override 
public void onFailure() { 
} 
})

At last we need to add these lines inside onDestroy method :

Code Block
@Override 
  protected void onDestroy() { 
    if (customerAllianceFeedback != null) { 
        customerAllianceFeedback.stopFeedback(); 
        customerAllianceFeedback = null; 
        } 
    super.onDestroy(); 
  }

Configuration

We can set the configuration as required like primary colour, headerAndTitleColor, ratingType, show or hide footer, frequency and paragraph text color.

Code Block
setPrimaryColor("#FF0000") 
setHeaderColor("000000") 
setParagraphColor("FFFFFF") 
setFrequency(Frequency.ONE) 
setShowFooter(true) 
setRatingScaleType("star")

Function names along with their use:  

Name 

Description 

Default value

SetPrimaryColor 

General theme color used inside the questionnaire  

popup. Pass a string value

#3B62B2

SetHeaderColor 

Color for headers and text of primary button. Pass a string value 

White

SetParagraphColor 

Color of text used in  

paragraphs. Pass a string value.

#586370

SetFrequency (Deprecated)

Pass .ONE or .INFINITE to show survey one or multiple times 

.ONE

setFrequency

We can give the value for delay in number of days for answered and closed.

Eg.
setFrequency(answered(Int),closed(Int)), setFrequency(answered(String),closed(Int)) , setFrequency(answered(Int),closed(String)), setFrequency(answered(String),closed (String)).
If the value entered is greater than 999999, it defaults to 999999.

.ONE

SetRatingScaleType("star")

Pass "star" for star rating type of question, "circle" for circle rating type of question and  "rectangle"  

for rectangle type rating question.

"rectangle"

We can set additional attributes in the SDK by using the following function: 

SetAttribute(attribute); where attribute is of type HashMap. 

Example: 

Code Block
Map<String, String> attribute = new HashMap<>(); 
attribute.put("key", "1234545456546"); 
customerAllianceFeedback.SetAttribute(attribute);