API docs

Website Library

Requirements

  • jQuery >= 1.8

Quick start

  • Register on SWAYco site
  • Go to account page
  • Press "Add an Website" button and fill the form
  • Copy distribution id at top of the page and application id of just added website
  • Add scripts to your page:

    <script type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script>
    <script type="text/javascript" src="//swayco.co/public/storage/jquery.sway.0.1.1.js"></script>
    
  • Init SDK:

    var swayIcon = new SwayIcon({
      distribution_id: 'distribution_id',
      application_id: 'application_id',
      onSuccess: function(surveyFrom) {
        // developer or researcher
        console.log('survey from', surveyFrom);
    
        // hide icon and survey:
        swayIcon.hideIcon();
      }
    });
    

API

Constructor

SwayIcon(<Object> options)

Creates new instance of SwayIcon.

options hash:

  • distribution_id - <String> Required. Get it in dashboard
  • application_id - <String> Required. You get it after adding new App or Website in dashboard
  • container - <DOM Node | jQuery Object>. If provided, survey will be placed inside this container immediately.
  • onLoaded() - <Function>. Callback, which will be called, when the survey will be successfully loaded (after .loadSurvey() call).
  • onQuestions(<Object> questions) - <Function>. Callback, which will be called after onLoaded. One argument with array of questions and answers for loaded survey.
  • onSuccess(<String> surveyFrom) - <Function>. Callback, which will be called after survey successful completes. One argument with String (developer or researcher). Shows whose survey was passed.
  • onTerminated() - <Function>. Callback, which will be called, when user choose terminating answer.
  • onAudienceMismatch() - <Function>. Callback, which will be called, if we do not have the survey for this user.
  • onError(<String> err) - <Function>. Callback, which will be called, if you enter invalid distribution_id or application_id, or on server error.

Methods

Load survey

.loadSurvey([<Object> options[,<Function> callback]])
  • options hash accept following CSS properties for future survey container:

    • left - Default: 'auto'
    • right - Default: '20px'
    • top - Default: '90px'
    • bottom - Default: 'auto'
    • width - Default: '500px' You can pass values in any valid jQuery format.
  • callback - function which will be called, when the survey will be successfully loaded.

Show Icon

.showIcon([<Object> options])

Show fixed icon on top-right of page. On click on this icon will be showed survey container.

  • options hash accept following CSS properties for future icon:
    • left - Default: 'auto'
    • right - Default: '20px'
    • top - Default: '90px'
    • bottom - Default: 'auto' You can pass values in any valid jQuery format.

Hide Icon

.hideIcon()

Hide icon and survey container.

Examples

Simple

<script type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script>
<script type="text/javascript" src="//swayco.co/public/storage/jquery.sway.0.1.1.js"></script>
<script>
  $(function() {
    var swayIcon = new SwayIcon({
      distribution_id: 'YOUR_DISTRIBUTION_ID',
      application_id: 'YOUR_APPLICATION_ID',
      onLoaded: function() {
        // the survey has been found and loaded. time to show Sway icon
        swayIcon.showIcon();
      },
      onTerminated: function() {
        swayIcon.hideIcon();
      },
      onAudienceMismatch: function() {
        swayIcon.hideIcon();
      },
      onSuccess: function(from) {
        // the user has successfully completed the survey. survey was `from` (researcher/developer)
        swayIcon.hideIcon();
      },
      onError: function() {
        swayIcon.hideIcon();
      }
    });

    // try to load the survey (if we have compatible survey for current user)
    swayIcon.loadSurvey();
  });
</script>

Complex

Mobile SDK for IOS(Download)

  1. Copy folder "SwaySDK" into your project in Xcode.
  2. Init sdk in your AppDelegate.m
    #import "SwaySDK.h"
    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
        [SwaySDK initSwayWithDeveloperId:@"DISTRIBUTION_ID"
        applicationId:@"APPLICATION_ID"];
        return YES;
    }
    

    DISTRIBUTION_ID - your unique token, you can find it in dashboard.

    APPLICATION_ID - when you create new app/website in dashboard, you get unique Application ID for this app/website, paste it here

  3. In your view controller
     #import "SwaySDK.h"

    User information may contain the following fields: country, state, city, age, gender, device, os, browser.

    country can be any string

    state can be any string

    city can be any string

    age can be one of: "13-17 yrs", "18-24 yrs", "25-34 yrs", "35-44 yrs", "45-54 yrs", "55-64 yrs", "65+ yrs"

    gender can be one of: "Male", "Female"

    device can be one of: "Desktop/Laptop", "Mobile", "Tablet"

    os can be one of: "Windows", "Mac", "Linux", "IOS", "Android", "Other"

    browser can be one of: "Chrome", "Firefox", "Safari", "Internet Explorer", "Other"

    To try to load webView:
    [[SwaySDK getInstance] tryLoadSurveyInView:self withData:dict]; //send NSDictionary with data if you have additional info about user
    To show side button:
    [[SwaySDK getInstance] showSurveyInView];
    To show survey form without showing button
    [[SwaySDK getInstance] showSurveyForm]
    To hide side button:
    [[SwaySDK getInstance] removeSurveyFromView];
    To turn on/off alert when users try to close survey:
    [[SwaySDK getInstance] showAlert:YES/NO];
    To set alert text:
    [[SwaySDK getInstance] setAlertText:@"Alert text"];
    To redraw survey interface (useful after device rotation):
    [[SwaySDK getInstance] redrawSurvey];
  4. If you want to get callbacks when survey is opened make your view controller
    <SwaySDKDelegate>
    -(void) surveyTriedLoad:(NSString*)_result{
       //tryLoadSurvey() callback
       //"webview_loaded" - webView was loaded
       //"audience" – user doesn't meet audience criteria
       //"wrong_id" – used wrong distribution/app id
    }
    -(void) swayOpened{
       //survey opened
     }
    -(void) swayClosed:(NSString*)_result{
       //survey closed
       //"terminated" –  survey was terminated
       //"success:researcher" – researcher's survey finished with success
       //"success:developer" – developer's survey finished with success
       //"canceled" – user canceled survey
    }
    -(void) questionReceived:(NSString*)_result{
       //survey questions in JSON format
    }

Mobile SDK for Android(Download)

  1. Add swaysdk.aar or swaysdk.jar library to your project
  2. Init sdk in your Activity
    SwaySDK.init("DISTRIBUTION_ID", "APPLICATION_ID", MyActivity.this);
    

    DISTRIBUTION_ID - your unique token, you can find it in dashboard.

    APPLICATION_ID - when you create new app/website in dashboard, you get unique Application ID for this app/website, paste it here

  3. In your activity
    Use sdk on UI thread.
    If you want to call it from another thread use:
    runOnUiThread(new Runnable() {
      @Override
      public void run() {
        // TODO Auto-generated method stub
      }
    });
    To load survey:
    SwaySDK.tryLoadSurvey(JSONObject object); //send empty object
    (new JSONObject()) if you have no additional info about user To show side button (don't show button if you got «no» in surveyTriedToLoad(String s)):
    SwaySDK.showSurvey();
    To show survey form without showing button
    SwaySDK.showSurveyForm();
    To hide side button:
    SwaySDK.removeSurvey();
    To turn on/off alert when users try to close survey:
    SwaySDK.showAlert(true/false);
    To set alert text:
    SwaySDK.setAlertText("alert text");

    User information may contain the following fields: country, state, city, age, gender, device, os, browser.

    country can be any string

    state can be any string

    city can be any string

    age can be one of: "13-17 yrs", "18-24 yrs", "25-34 yrs", "35-44 yrs", "45-54 yrs", "55-64 yrs", "65+ yrs"

    gender can be one of: "Male", "Female"

    device can be one of: "Desktop/Laptop", "Mobile", "Tablet"

    os can be one of: "Windows", "Mac", "Linux", "IOS", "Android", "Other"

    browser can be one of: "Chrome", "Firefox", "Safari", "Internet Explorer", "Other"

  4. Add this permissions to your app AndroidManifest.xml
    <uses-permission android:name="android.permission.INTERNET" />
      <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  5. If you want to get callbacks register new SurveyListener
    SwaySDK.instance.registerListener(new SwaySDK.SurveyListener() {
      @Override
      public void onSurveyClosed(String s) {
        //survey closed
        //"terminated" –  survey was terminated
        //"success:researcher" – researcher's survey finished with success
        //"success:developer" – developer's survey finished with success
        //"canceled" – user canceled survey
      }
      @Override
      public void surveyTriedToLoad(String s) {
        //tryLoadSurvey() callback
        //"loaded" – webView was loaded
        //"Error …" –  survey webView loading finished with error
        //"no_internet" – no internet connection
        //"audience" – user doesn't meet audience criteria
        //"wrong_id" – used wrong distribution/app id
      }
      @Override
      public void onQuestionReceived(String _result) {
        //JSON string with questions that will be shown to user
      }
      @Override
      public void onNoInternetConnection(String _result) {
        //"no_internet" - no internet connection
      }
    });

SDK for Unity(Download)

  1. Add Sway.unitypackage to your project
  2. Sway.devId = "DISTRIBUTION_ID";
    Sway.andAppId = "ANDROID_APPLICATION_ID";
    Sway.iosAppId = "iOS_APPLICATION_ID";
    

    DISTRIBUTION_ID - your unique token, you can find it in dashboard.

    ANDROID_APPLICATION_ID and iOS_APPLICATION_ID - when you create new app/website in dashboard, you get unique Application ID for this app/website, paste it here

  3. Implement Sway.SurveyListener interface
    Sway.Instance.RegisterListener(this); - register listener
      void Sway.SurveyListener.OnSurveyClosed(string s){
        //Survey closed (s - message)
        //"terminated" –  survey was terminated
        //"success:researcher" – researcher's survey finished with success
        //"success:developer" – developer's survey finished with success
        //"canceled" – user canceled survey
      }
      void Sway.SurveyListener.SurveyTriedToLoad(string s){
        //Survey tried to load
        //"webview_loaded" - webView was loaded
        //"audience" – user doesn't meet audience criteria
        //"wrong_id" – used wrong distribution/app id
      }
      void Sway.SurveyListener.OnQuestionReceived(string s){
        //Question received
        //survey questions in JSON format
      }
    To try to load webView:
    Sway.TryToLoadSurvey(jsonString); //send json formatted string with data if you have additional info about user
    To show side button:
    Sway.ShowSurvey();
    To show survey form without showing button
    Sway.ShowSurveyForm();
    To hide side button:
    Sway.RemoveSurvey();
    To turn on/off alert when users try to close survey:
    Sway.ShowAlert(true/false);
    To set alert text:
    Sway.SetAlertText(alertText);

    User information may contain the following fields: country, state, city, age, gender, device, os, browser.

    country can be any string

    state can be any string

    city can be any string

    age can be one of: "13-17 yrs", "18-24 yrs", "25-34 yrs", "35-44 yrs", "45-54 yrs", "55-64 yrs", "65+ yrs"

    gender can be one of: "Male", "Female"

    device can be one of: "Desktop/Laptop", "Mobile", "Tablet"

    os can be one of: "Windows", "Mac", "Linux", "IOS", "Android", "Other"

    browser can be one of: "Chrome", "Firefox", "Safari", "Internet Explorer", "Other"

  4. Add this permissions to your app AndroidManifest.xml
    <uses-permission android:name="android.permission.INTERNET" />
      <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

    and add android:hardwareAccelerated="true" into your "application" section.