This article will cover various use cases and corner cases for targeting users. See the User Targeting Overview (Settings Page) for higher-level information.

Time-based Targeting

Below is an example Javascript code snippet to save your users' current local time. We've included different time value examples to illustrate different use-cases for targeting by time using the properties in the identify.call. This snippet would ideally be placed right after your users successfully log into your site.

const currentTimeString = new Date(); // Tue Mar 27 2018 18:09:27 GMT-0400 (EDT)  

Appcues.identify('abc-123', { 	 	
	currentDayOfWeek: currentTimeString.getDay(),    // 0=Sunday, 6=Saturday  	 	
	currentDayOfMonth: currentTimeString.getDate(),  // 1-31 	 	
	currentHour: currentTimeString.getHours(),       // 0-23 	 	
	currentMonth: currentTimeString.getMonth()       // 0=January, 11=December  
});

Example Use Cases

1. Only display flow after or before a certain time of day (localized): 
If for example you'd only like to target a flow to users during business hours, from 9am-5pm, you can use the user properties sent in above to do so!

Note:  The following example will use military time: 0-23

Open the flow settings for your desired flow and scroll down to the  Audience section. Select 'Specific users' > 'Property' > 'Current Hour' > 'greater than' > {insert desired beginning time - Ex. 9}

Then choose 'Add Another' (green button) to create an additional field: 'Property' > 'Current Hour' > 'less than' ---> {insert desired end time - Ex. 17}

ProTip: If instead, you'd prefer to only show the flow after a certain time (ex. after 5pm) you can use just the 'greater than' setting shown above ['current hour' > 'greater than' > 17]. We will stop showing the flow at the localized midnight (ie. the 23rd hour).

2. Display a flow before a certain date or up until a certain date (Localized): 
Sometimes you'll only like for a flow to be shown before/until a specific date. There may be a feature announcement that you'd like to show starting now until this coming Saturday, or a webinar notification until a specific date, you can use the 'Updated at' property to set this up.

Open the flow settings for your desired flow and scroll down to the  Audience section. Select 'Specific users' > 'Property' > 'Updated at' > 'occurred before' ---> {insert desired end date}

Note:  In the example below with the end date of 3/31/2018, this flow will show until 12am 3/31/2018 of your end-users specific browser time setting.  While the flow will not show after that date it will still remained published in your dashboard.

3. Display a flow only during a specific month: 
Let's say you have a flow that you'd only like to run during the month of January. You can accomplish this using the 'current month' property.

Open the flow settings for your desired flow and scroll down to the  Audience section. Choose 'Property' > 'Current Month' > 'equals' > { insert month number (ex. January = 0, December = 11) }

4. Display a flow only on a specific day of a month  
If you happen to have a flow that you always want to show on a certain day of the month you can use the 'Current Day of Month' property to do so. You can even do fancy things like show the flow for the last days of the month like we'll show below (ex. "Last day of the month sale!" that shows only for days following the 25th of the month)

Open the flow settings for your desired flow and scroll down to the  Audience section. Choose 'Specific users' > 'Property' > 'Current Day of Month' > 'is greater than' -->{insert day (ex. 25) }

Note:  In the examples above, given the settings the flow will not show but it will still remained published in your dashboard.

Localization / Multiple Languages

There are several ways to localize a flow. What method you use depends on the number of languages you use, the level of customization required, and your comfort with HTML.

Method 1: Create a Separate Flow Per Language

To begin, create your flow in a base language, including all design elements and targeting necessary.

Then, clone the flow to create a copy for each language you'd like to target. Rename each copied flow based on the language you'll be entering, then edit each flow to change it to the specified language.

Finally, before publishing, add a targeting rule to limit the flow to display only for the appropriate language.

To make organization easier, it might be a good idea to create a specific Tag on your flow dashboard to contain the language variations of your flow.

In order to make changes to this set of flows, you'll have to alter each flow individually. This is why we recommend this method only for a few translations at once; if it becomes unwieldy, continue to Method 2 and decide if it will work better for your needs.

Including or Excluding Dialect

For added power, you can choose to target just specific variations or dialects of a particular language. In the example above, we've targeted just Hong Kong Chinese. By searching "Chinese", you'll see all of the options Appcues allows you to target:

If you select the first option, "Chinese (all)", your targeting will include all of the Chinese dialects. To be specific, select just the ones you want. This goes the same for all other languages we offer (English, German, Spanish, etc.).

To target more than one dialectic, just click Add Another and choose the next dialect. Be sure to specify if this is ALL or ANY targeting. You may need to add a group if you have other targeting rules, in order to organize your language rules in one place.

Method 2: Use HTML Blocks for Different Languages in One Flow

This method is more advanced, but may help make creating and managing flows in multiple languages significantly easier.

To translate within one flow, create your flow normally, but for any text blocks, use the HTML component (Advanced > HTML) instead of the Text component whenever you need to add localized text.

Within each HTML component, enter the following HTML as a template:

<div>     Show in English. </div>  <div>     Afficher en français. </div>  <style type="text/css">     /* Don't edit this part */     .lang { display: none; }     .lang.{{_lastBrowserLanguage}} { display: block; } </style>

Change the template for your own needs, adding <div> blocks, entering the translated content inside, and specifying the language using the format as shown above.

For each language, only the blocks with the "class" attribute of the given language will be displayed. The ones not matching the current user's language will be hidden completely.

Note that you can use any HTML you like, as long as you affix the class "lang" as well as a class for the language under which the element should show up, for example:  <h1>Willkommen auf meiner Seite</h1> In that way, you can localize titles, paragraphs, links, and more. You may also choose to nest many elements inside one DIV for the given language to group all content for that language in one place.

Fallbacks

One limitation of this method is that there's no way to easily specify a fallback "default" content for languages that you do not specify in a block. For example, if I wanted to specify French and English and have all other languages default to English, that would be difficult.

The way around this is to include classes for all unused locale codes on the block you'd like to be the default. Although there will be many locale code classes on one element, it will still work and display for the remainder of languages.

Using Your Own Language Custom Property 

If you don't use the default browser language to determine the user's language preference, this method will still work. Just send us the language code or specifier as a custom property when calling Appcues.identify() (more information here), and use that custom property identifier in place of {{_lastBrowserLanguage}} in the code above.

Bonus

This method can work to quickly personalize content for any custom property with text values. As long as the custom property has a limited number of values, then you can specify which HTML blocks to show or hide based on those values. This is unsupported, but you can modify the CSS above to achieve it.

New User Targeting

If you just signed up and installed Appcues, you might ask yourself, "How do I create content only for people who sign up  after today?" Appcues has you covered.

In order to accomplish this, at least one of the following requirements need to be met:

1. You are sending a created_at property to Appcues that denotes when a user signed up, or
2. You're identifying your users with a numeric user ID that increments for each new users.

If you haven't met one of those criteria, check out our docs on how to send user properties.

1. Targeting by signup date

Once you're sending the date when users signed up, you can use Appcues' targeting features to send your flows only to users who sign up after today. To do that, select the  Created At property and use the is greater than operator to target only users who sign up after the current date.

NOTE: You can target users based on this date by using the "is less than" and "is greater than" operators, as long as you specify the date in "YYYY-MM-DD" format.

2. Targeting by user ID

If you have incrementing, numeric user IDs, you can target new users by "pivoting" based on the current ID. For example, if the last person who signed up has the user ID 1023, targeting users whose User ID property is greater than 1023 means only users who sign up later will see your flow.

Both of the above methods use property targeting to select only new users. You can find more information about this feature of Appcues on our property targeting docs.

Targeting by IP Address

Appcues does not allow for targeting by IP address by default.  We do, however, provide an API endpoint that can be used to include a user's IP Address as a User Property. This setup requires a slightly customized `Appcues` (or `analytics`, if using Segment) `identify` call, as illustrated in the examples below. To enable it, simply follow the example that best fits your app.

API Endpoint

The following endpoint will return the requestor's IP address, which can then be passed to Appcues as a User Property...

https://api.appcues.net/v1/remote_ip

Examples

The following examples are provided for illustrative purposes.  The strategy you ultimately use will depend on how your app is built, but chances are one of the following will seem familiar.

Alternative 1: Use JSONP and a callback function (great for older, server-rendered sites)

<script src="//fast.appcues.com/<YOUR_APPCUES_ID>.js"></script>
<script>
    function appcuesIdentifyWithIP(json) {
        Appcues.identify('<USER_ID>', {
            ip: json.remote_ip,
            email: 'user@email.com',
            name: 'user name',
            addtlProp0: 'addtlProp0'
        });
    }
</script>
<script type="application/javascript" src="https://api.appcues.net/v1/remote_ip?callback=appcuesIdentifyWithIP"></script>

Alternative 2: Use jQuery (the easiest option, if you're including it already)

<script src="https://code.jquery.com/jquery-1.12.4.min.js"></script>
<script src="//fast.appcues.com/<YOUR_APPCUES_ID>.js"></script>
<script>
    $.getJSON("https://api.appcues.net/v1/remote_ip", function(json) {
        Appcues.identify('<USER_ID>', {
            ip: json.remote_ip,
            email: 'user@email.com',
            name: 'user name',
            addtlProp0: 'addtlProp0'
        });
    });
</script>

Alternative 3: Use the new Fetch API (best for ES6 codebases packaged with Webpack/similar)

<script src="//fast.appcues.com/<YOUR_APPCUES_ID>.js"></script>
<script>
    fetch("https://api.appcues.net/v1/remote_ip").then(function(response) {
        return response.json();
    }).then(function(json) {
        Appcues.identify('<USER_ID>', {
            ip: json.remote_ip,
            email: 'user@email.com',
            name: 'user name',
            addtlProp0: 'addtlProp0'
        });
    });
</script>

As always, feel free to reach out for more specific guidance.

Can I block an IP or user?

We don't currently have a way to block an IP or a user within Appcues, but you can use user targeting to specifically block a user or IP.

Targeting by Location (GeoLocation)

This document will outline what you will need to add to your Appcues.identify() call and how to then target by location.

*NOTE* Geolocation must be enabled by your users in order for location to be collected. Be sure to test this implementation for instances where users have and have not enabled it in their browser.

In addition, the geolocation function may timeout. We recommend ensuring that the location call has been successful before passing coordinates to the Appcues.identify call.

Below is an example Javascript code snippet to add location coordinates to your Appcues.identify call

function getLocation() {
    if (navigator.geolocation) {
        navigator.geolocation.getCurrentPosition(showPosition);
    } else {
        return false;
    }
}
function showPosition(position) {
   	 return position.coords; 
}

const currentLocation = getLocation() ? getLocation() : null;

Appcues.identify('aaa-bbb-ccc', {
	currentLatitude: currentLocation.latitude,
	currentLongitude: currentLocation.longitude
})

How to target by Location:

In this example, we'll focus on the Appcues HQ right here in Massachusetts: Latitude 42.363175, Longitude -71.059233.

Now, we're going to target our neighbors by using the area around our location. This area will be represented by a square region located inside these coordinates:

top left
42.364129, -71.063396

top right
42.364286, -71.056401

bottom left
42.360261, -71.063396

bottom right
42.360261, -71.056401

To find your own Latitude and Longitude coordinates: https://www.latlong.net/

In your desired flow's Audience section in the 'Target and Publish' step, choose 'Property' --> 'Current Latitude' --> 'greater than/ less than' ---> {insert desired latitude}

Choose the 'Add Another' green button and repeat but this time choose occured after: 'Property' --> 'Current Longitude' --> 'greater than/ less than' ---> {insert desired longitude}

Show on Scroll

Appcues provides a way to trigger a flow at any time using the Javascript call "Appcues.show (FLOWID)". This can be used to show a flow when a user takes a specific action on a page in your application. Below we'll cover how to use this call to show a specific flow on scroll just like we've done in our docs!

NOTE: This option requires you to add code within your application, and cannot be implemented without development work. You'll need to add the show call to the appropriate section of code within your application. You can find more information on this and other calls is in the Javascript API doc.

Example

We use a Javascript call within the example below to trigger the Slideout after you've scrolled more than 75% down the page. Take a look below. 

To achieve this we added the following snippet to the code for the pages desired:

window._appcuesshown = false;
window.onscroll = function(e) {
if (!window._appcuesshown &&
((window.scrollY + window.innerHeight) / document.body.scrollHeight > 0.75)) {
window._appcuesshown = true;
Appcues.show(“FLOWID”);
}
};

You'll want to update the FLOWID above to the Flow ID that you'd like to show upon scroll. Finding Your Flow ID

Important Disclaimer

It's necessary to note that anytime you're using Appcues.show(), all targeting rules will be ignored. This can result in a show once flow showing multiple times and/or the flow showing to people outside of the Audience targeting. The analytics page will show the stats for the flow and the CSV will have the form results as normal.

Another thing to keep in mind is that if you'd like to switch this flow out for another one in the future, you may need to get your developers involved so they can update the snippet above.

There is currently no way to trigger Appcues flows on scroll while also respecting targeting.

If you have specific questions about the above, feel free to reach out to us at support@appcues.com for assistance.