• Quick Start
  • Send Survey
  • Get Contact
  • Remove Contact
  • Delete Contact (GDPR)
  • Get Unsubscribed
  • Get Responses
  • Get NPS
  • Sent Statistics
  • Historical Stats
  • Deactivate All
  • Bulk Add with CSV
  • Inapp Surveys
  • Bulk Add/Send

Change Log

  • Changes

Inapp Survey Flow

The AskNicely in-app survey flow is a three step process for those interested in a non-standard way of displaying a survey to their customers, such as through a website or within their mobile application.
It involves creating a secure one-time use hash on your server, using it to negotiate with AskNicely to generate a survey slug, and using that slug to display a survey to your users.

Generating An Email Hash

To generate your email_hash simple examples are shown below (you will need to adjust them to your code).
You will need to use the below secret key to hash a contact's email address:

secret_key
  • PHP
  • Ruby
  • Python
  • Java
  • C#
  • email_hash: "<?php echo hash_hmac(
                'sha256',
                $user->email,
                'secret_key'
                ); ?>"
    
  • email_hash: "<%= OpenSSL::HMAC.hexdigest(
                 'sha256',
                 'secret_key',
                 current_user.email
                 ) %>"
    
  • email_hash: "{{ hmac.new(
                        'secret_key',
                        request.user.email,
                        digestmod=hashlib.sha256).hexdigest()
                        }}"
    
  • import javax.crypto.Mac;
    import javax.crypto.spec.SecretKeySpec;
    
    public class ApiSecurityExample {
        private final static char[] hexArray = "0123456789abcdef".toCharArray();
    
        private static String bytesToHex(byte[] bytes) {
            char[] hexChars = new char[bytes.length * 2];
            for ( int j = 0; j < bytes.length; j++ ) {
                int v = bytes[j] & 0xFF;
                hexChars[j * 2] = hexArray[v >>> 4];
                hexChars[j * 2 + 1] = hexArray[v & 0x0F];
            }
            return new String(hexChars);
        }
    
        public static void main(String[] args) {
            try {
                String key = "secret_key";
                String message = "user@example.com";
    
                Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
                SecretKeySpec secret_key = new SecretKeySpec(key.getBytes(), "HmacSHA256");
                sha256_HMAC.init(secret_key);
    
                String hash = bytesToHex(sha256_HMAC.doFinal(message.getBytes()));
                System.out.println(hash);
            } catch (Exception e) {
                System.out.println("Error");
            }
        }
    }
    
  • using System.Security.Cryptography;
    
    public class ApiSecurityExample
    {
        private static string CreateHash(string message, string secret)
        {
            secret = secret ?? "";
            var encoding = new System.Text.ASCIIEncoding();
            byte[] keyByte = encoding.GetBytes(secret);
            byte[] messageBytes = encoding.GetBytes(message);
            using (var hmacsha256 = new HMACSHA256(keyByte))
            {
                byte[] hashmessage = hmacsha256.ComputeHash(messageBytes);
                return System.BitConverter.ToString(hashmessage).Replace("-", string.Empty).ToLower();
            }
        }
    
        public static void Main(string[] args)
        {
            string key = "secret_key";
            string message = "user@example.com";
            System.Console.WriteLine(ApiSecurityExample.CreateHash(message, key));
        }
    }
    

Test Your Email Hash

Requesting a Survey Slug

Request a Survey Slug

Survey slugs are used to identify who is receiving the survey and record their responses in a safe and secure manner.

Make a POST request to
POST https://DEMO.asknice.ly/service/inapp.php?id=uuid

with the body:
            {
                "domain_key":"DEMO",
                "template_name":"default",
                "name":"Erwin Schrodinger",
                "email":"schrodinger@example.com",
                "email_hash":"df462ce404bbae11bd4e5860682db02e86ccace29b1a4d631dc7fbe075e321c5",
                "created":"1418350105",
                "force":true,
                "a_custom_property":"Sample String",
            }

Arguments

Query Arguments
Argument Example Required Description
uuid 2ee42628423611ed Required We require a one-use dash-free 16 length uuid to prevent duplicate spam.
Body Arguments
Argument Example Required Description
domain_key DEMO Required The domain you signed up to AskNicely with.
template_name default Required The template name of the survey you want to use.
name Erwin Schrodinger Required The name of the person being surveyed.
email schrodinger@example.com Required The email address of the person being surveyed.
email_hash ABCDEF0123456789 Required The email address of the person being surveyed after having been hashed through your secret key. See the above "Generating An Email Hash" section.
created 1418350105 Required A unix timestamp (seconds since 01/01/1970) of when this customer joined your service.
force true Optional Whether to 'force' the survey/ignore set contact rules. This is intended for testing during development, and will prevent the survey from triggering workflows. Please do not use this in production!
a_custom_property Sample String Optional Any number of custom properties beyond the above are supported. They will be stored against the person and question for your later use.

Response

            {
              "wait": 86400,
              "slug": "abcdefghijkl",
              "show": true,
              "id": 123456,
              "info": ""
            }
Response Variables
Variable Example Description
id 123456 The id of the prepared survey.
slug abcdefghijkl The slug to use when displaying the generated and prepared survey.
wait 86400 In the case of failure, this will show how long to wait before attempting to make another survey.
show true Whether to immediately show the survey. When used with the web in-app experience this is tied to the automatic javascript, but can be ignored outside that context.
info Any extra error/status message that may come with the survey. Usually only populated if there was an error preparing the slug.

Displaying Your Survey

Once you have a survey slug, you can display the survey using an iframe, by opening another browser window, or (for mobile applications) loading the URL in a WebView.

Load the url:
GET https://DEMO.asknice.ly/email/conversation/slug?template_name=template_name&inapp=inapp

Query Arguments
Argument Example Required Description
slug 2ee42628423611ed Required The previously obtained slug that is to be loaded and used to display your survey.
template_name default Required The template name of the survey you want to use.
inapp Required Whether this survey is considered 'in app' or not. Affects some display rules and is typically not used by custom/mobile implementations, but is used by the AskNicely Javascript implementation.

For mobile implementations, the page returned implements a message handler under the name askNicelyInterface.
These events return a standard object that consists of a 'event' and 'msg' (message).
The current available events are as follows:

askNicelyInterface Events
Event Triggered By Description
askNicelyDone The survey being completed by the person being surveyed. A 'msg' of 'Success' indicates that the survey was completed successfully, and is usually used to automatically close the survey display when outside of a web browser window.

For those who already have accounts with AskNicely, we provide a prebuilt JavaScript implementation to automatically display AskNicely on your website. Please ask one of our wonderful Customer Success crew members for more information!