In-app Touchpoint activities

Leverage Touchpoint to deploy contextual, targeted and visually engaging activities directly in your mobile apps. Gain insights into the app experience, collect brand sentiment, and enrich your customer profiles to better understand those engaging with your brand.

To support a seamless workflow, we developed a mobile SDK to enable an integration between Touchpoint and your mobile apps. A central design goal of the SDK is to require only an upfront effort from the mobile app developer, thereby eliminating any ongoing effort related to distributing different activities.

On the admin side, once the SDK is integrated, the distribution of Touchpoint activities can be done with a single click, without the need to release a new version of the mobile app or make any code changes.

This document outlines the workflows for both the mobile app developer who will perform the one-time integration, and the Touchpoint admin who will deploy activities directly to the mobile apps.

Before getting started, let's go over a few terms:

  • Touchpoint activity: an activity created by a Touchpoint admin in Touchpoint.
  • Touchpoint distribution: The process of sharing Touchpoint activities with your broader audience. Touchpoint activities can be distributed in different ways and in different places. In this document, we are diving into the distribution via the mobile app. A distribution is linked to a Touchpoint activity.
  • Screen name: a unique label given to a specific screen, view or page on a mobile app. Some examples are Login, Product List, Product Detail, or Settings. A Touchpoint activity can be assigned to a particular screen. Multiple activities can be displayed in different screens in your app.
  • Respondent: the end user interacting with the mobile app. The app can set any attributes for the current visitor. Some examples are email, an internal unique identifier, shoe size, etc. These attributes are sent to Touchpoint and can be exported by Touchpoint admins.
  • Attributes and Targeting: Touchpoint can target certain visitors based on their attributes. Within Touchpoint, certain targeting rules can be set so that an activity will only be displayed to respondents whose attributes match the defined rules. An example of an attribute is location, loyalty program status, or interest in a certain product.

Integration (Integrate Touchpoint with your mobile app)

We support an integration with the following app platforms:

  • iOS
  • Android
  • React Native
Once the integration is successfully implemented, the following information is collected from users and visitors:
  • User Agent String: Shows the browser version, device make/model, and so on.
  • Device ID on mobile devices
  • OS type and version
None of this is personally identifiable information (PII). This information is not stored in cookies.

Touchpoint Admin

As a Touchpoint admin, you will be initiating the integration between Touchpoint and your mobile apps. This process is as follows:

  1. Start the registration process by navigating to the Digital Channels page and clicking New Channel.
  2. Name your app in Touchpoint. Each app will require its own integration so give each app an easily recognizable name.
  3. Each app integration will require its own API key and API secret. These are unique, per-app credentials that allow Touchpoint to make a secure connection with your app. You can think about it as a unique user ID (API key) and password (secret).
  4. Once you have completed the registration process for all the apps you would like to integrate with Touchpoint, copy and send the API keys and secrets to your mobile app developer along with the technical documentation to complete the integration.
Best Practice Tip: Before meeting with your developer, consider the customer journeys you would like to surface Touchpoint in. What screens would you want the activity to appear in? Are there any UI elements that if clicked on, should show the Touchpoint activity?

Your mobile app developer will need to register those screens and components during the integration process. Having that information will reduce internal delays.

Mobile App Developer

As a mobile app developer, refer to the relevant documentation in GitHub:

Distribution (Distribute activities to your mobile app)

Touchpoint Admin

  1. Once your activity is ready to be deployed, proceed to the Distribute stage.
  2. Click New Distribution.
  3. Select Display in your app.
  4. Name your distribution and select which app you would like to deploy to.
  5. Proceed to the Appearance & Behavior tab to determine how your activity will surface in your app.

There are three possible activity presentations:

  • Pop-up
  • Custom component
  • Banner

Pop-up

A pop-up displays the specified activity when the respondent lands on the specified screen. The activity fills the entire view port and becomes the focal point for your respondent.

You can configure a pop-up to appear:

  • After a specific delay, or display instantly.
  • Every time a respondent lands on the specific screen, or until the respondent interacts with the activity (by either responding or dismissing the activity). The latter is recommended for an optimal respondent experience.

Custom component

Custom components are UI components built by mobile app developers and maintained in your own mobile app codebase. Clicking on or otherwise invoking these components will open a Touchpoint activity inside of a webview.

Custom component behavior

  • A single screen can have multiple custom components. Each one of those components could trigger a unique activity.
    Example

    screen: Home, component: Lightbulb

    screen: Home, component: QuestionMark

    Lightbulb can invoke Activity A, and QuestionMark can invoke Activity B.

  • A custom component can be set to be persistent so it will trigger the activity even if the visitor has already seen it. This scenario is useful for a use case like a "collect feedback" button where you always want the respondent to be able to respond to the activity. On the Appearance & Behavior tab, under Visitors will see this activity, select Persistently.

Banner

Banners are out-of-the-box UI components that the SDK can render at any time, on any screen you specify, without the need for code changes to the mobile app. When participants tap a banner, a Touchpoint activity opens inside a webview. Because banners are out-of-the-box, there is limited design flexibility.

A banner has these main attributes which you will be able to set in the Touchpoint UI:

  • Style: what does the banner look like on the mobile app? The style object includes text color and background color.
  • Caption: the text that is shown on the banner.
  • Screen name: which screen in the mobile app should show which particular banner.

The default height of the banner is 70px and it is configurable by the mobile app developer.

Banner behavior

  • The banner will remain persistent as the respondent navigates from screen to screen until either clicked or dismissed.
  • The banner will cover the content underneath it.
  • The presentation of a banner counts as a view in reporting.
  • If a respondent taps the X to close the banner without opening the activity, Touchpoint will track the event and won't show the same banner again. A collapsed banner will not impact reporting.
  • The position of the banner cannot be changed at this time. All banners render on the bottom of the screen.
  • As a rule, only one banner will be displayed on a screen at any one time. If there are multiple banners distributed to the same screen (which the SDK distinguishes using the screen name), the respondent sees only one banner on each visit. The next time they visit the same screen they will see the next banner.
  • For multilingual activities, the banner will show text in the appropriate locale.

Once the appearance and behavior is set, proceed to the Attributes tab where you can determine who will see the Touchpoint activity you just created: your entire broad app audience, or a specific set of the app visitors.

Targeting

You likely already have quite a bit of data that you know about your app visitors. You might know when they joined the app, when their last purchase was, their unique segments as it corresponds to your organization and some personal characteristics such as marital status, geographical location, etc.

User attributes allow the mobile app developer to pass some of those valuable data points into Touchpoint via the SDK so you can target specific activities to a specific segment of your audience. This will allow you to learn more from the visitors you care about the most and build up your knowledge about your audience with every activity.

In the Attributes tab, build your targeting condition and determine which attributes you will leverage to reach your intended audience. Targeted distributions can help you:

  • Target specific audience segments with activities that are relevant to their own customer journeys and unique interactions with your brand.
  • Personalize the tone and the types of questions you are asking to ensure you are collecting the right data from the right people to inform your business decisions.
  • Distribute the activity to only those you care about, reducing the burden and minimizing interruptions to your audience as a whole.
Best Practice Tip: There is no limit to the number of visitor attributes you can pass into Touchpoint, but we do recommend thinking through your strategy to prevent an overload of unnecessary data points. What kind of questions will you ask? Who are your valuable segments? Any upcoming campaigns or business goals that you should keep in mind?
Important: Do not leverage visitor attributes to pass personally identifying information (PII) into Touchpoint.

To protect visitor privacy, do not pass data into Touchpoint that could be considered personally identifiable information (PII). PII includes, but is not limited to, information such as social security numbers, personal home addresses, credit card numbers, financial account numbers, street addresses, and so on.

FAQs

  1. Do my visitors leave the app when they interact with the activity?

    No. The visitor remains within the app and the activity will open up in a webview embedded inside the app alongside the native code.

  2. Do you track any respondent information from the app?

    We track device IDs on iOS and Android to track the visitor's activity. This is to prevent showing the same activity to a respondent once the activity has been completed.

  3. What happens after the respondent closes or completes the activity?

    The respondent will stay on the same screen of the app without any change in the state of the app. The SDK won't show the same activity again to the same respondent unless the activity is set to always show.

  4. Can I distribute the same activity to my app on different screens using different activity presentations?

    Yes. You can create multiple distributions for the same activity so it appears in different ways across your app. The same activity could be generated as a pop-up on one screen, as a custom component on another screen, and as a banner on the third screen.

  5. If I distribute my activity to my mobile app and my website and my respondent visits both digital channels, will they see the activity multiple times?

    As long as you leverage the visitor payload and you track their unique ID across both digital channels, the respondent will not see the same activity again assuming they either dismissed it, or completed it. Touchpoint will recognize and respect the interaction across both digital channels.

  6. Can the SDK handle offline activity completion?

    Not at this time. The SDK will check if there is internet connectivity before displaying an activity and will not load or operate if there isn't.

  7. What is the size of the SDK?

    • Android binary is 80KB.
    • iOS binary is 5.4MB

  8. Can an activity be triggered based on custom events in the app (a purchase was just completed) or based on a time stamp (visitor is returning to the app for the first time in 6 months)?

    Yes. The function openActivityForScreenComponent can be used to generate custom logic so the activity can appear wherever and whenever you would like.

Troubleshooting

I integrated my app and deployed an activity but it is not showing up in the app. What should I do?

Before reaching out to Tech Support, check for the following steps:

Touchpoint Admin:

  1. Are the activities triggered by a banner, pop-up? If so, is the screen name being set correctly?
  2. If the activity is triggered by a custom component, are you calling it with the correct screen name and component name?

Mobile App Developer

  1. If you enable debug logs, are you seeing anything when you set the screen? Is the SDK able to find a trigger associated with that screen name?
  2. If the activity is triggered by a custom component, are you seeing any logs showing that a trigger was or wasn't found?
  3. If the activity is not showing up, is it technically already viewed by your current visitor? If so, try disabling the API filtering OR try changing your visitor ID. Does it appear then?
  4. Check for typos. For example, typing compomentName: instead of componentName: (notice the typo of the 'm' instead of an 'n') could lead to an error.

The Mobile App SDK is not included with your Community. If you're interested in gaining access to this feature, please contact your Customer Success Manager or your Account Executive.