Building a Best Practice Integration User Experience

For this post, we teamed up with our friends at PartnerFleet.io. They provide a turnkey marketplace platform to help companies promote and scale their partner and integration ecosystems. 

SaaS product integrations are about mechanics. They are about moving data from between systems.

But, they are also about the experience your users have. How do they enable and use the integration?

There is a lot of variety in integration user experiences across different products. If you’re a business software user, you’ve likely interacted with many of them.

In this post, we aim to help you understand how a user thinks about integrations. The goal is to help you design an integration user experience that best meets your users' needs.

Why User Experience Design Is Important For Integrations

When you build a software product, the experience you create for your users is important. You must understand your users’ jobs to be done. You must understand their emotions while doing those jobs. You must help them achieve their goals.

When providing an integration, better described as creating a cross-product user experience, the same idea applies.

Integrations can produce some specific anxieties. It's so important to focus on addressing those anxieties.

You should consider how to address these common user anxieties related to integration:

• Integration Availability (Are the integrations I want available?)
• Integration Capabilities (Does the integration do what I need it to?)
• Integration Quality (Does the integration work well?)
• Integration Setup Difficulty (How hard is it to make the integration work?)
• Integration Confidence (Is my integration still working?)

These anxieties will usually appear while a user evaluates your product. Its important to understand how they impact your ability to convert them to a customer.

The following sections cover each anxiety.

Integration Availability

Any user of a B2B software product will have a dozen or more other software products they use every day.  Knowing that you integrate with those products will be key, especially during evaluation.

Your product solves a certain problem in a broader patchwork of problems. Your user will want to know if your product plays nicely with the rest of the products they work with. Doing their job requires all those products.

Phrased another way, your user will ask: “Are all the integrations I would want available?”

You might have the best product in the world at solving the problems you are best at solving. If you can't interoperate with your user’s other critical systems, it won’t matter.

Integration Capabilities

Once a user identifies an integration they want to use, the user will focus on that integration. (This will happen, times every integration they want to enable.)

It’s one thing to see the logo for the integration you're looking for. It’s another thing for that integration to work in ways that solves your problem.

The natural next question for your user to ask is, “Does this integration do what I need it to do?”

If the integration doesn't meet your users cross-product requirements, it doesn’t provide value to them. If it doesn't provide value to your user, it's no good for you either.

Integration Quality

The natural next question for them is, “Ok, but does the integration actually work?”

We’ve all experienced integrations that don’t work, and it can be very frustrating. Users will be rightfully skeptical that you will provide a high quality integration. After all, you probably aren't an integration company.

If the integration doesn’t work well, it also won’t provide value for your user. Again, this is no good for you.

Integration Setup Difficulty

Most users aren’t well-versed in the complexities of software integration. Even the simplest integrations can require some difficult decisions during the set up.

A natural question for a user to ask is, “How hard is this integration?” and “What if I get stuck?”

Ideally, your user will never get stuck! Ideally, your integration’s user experience is smooth and simple. In reality, that won’t always be possible. You must reduce your user’s natural anxiety about setting up the integration.

Integration Confidence

If you squash all the anxieties that stand in your user’s way, your user might start to use the integration. Then they will ask, “How do I know that it’s working?”

Integration is mostly back-end functionality. It’s data going into and out of APIs. The user typically only interacts with the outcome of the integration. They see data go into and come out of the integrated system. They rarely interact with the integration itself. To the user, integrations work a little like magic.

It’s hard for most users to know that everything is working well–that data isn’t dropped and gone forever. Maintaining ongoing confidence in the integration requires some level of visibility.

User Experience Considerations When Providing Integrations

No two integrations are the same. From one product to the next, integrations to common systems like Salesforce or Hubspot are even different .

When providing an integration to your users, you should consider what is unique to your users. Who are your users? How do they think? What problem are they trying to solve that is unique to how they use your product?

You must design the integration experience for your specific users and their challenges. Consider the following questions to help think through what that should be.

How much should be self-setup versus assisted?

Sometimes integrations are easy to set up, so your user can click a few buttons and data starts flowing. Sometimes the integrations are complex. Those complex integrations often require help or full-on projects.

Product teams assume they should provide self-setup integrations. It's often the correct decision. It’s not necessarily the correct approach to take every time.

This bias often comes from trying to be “hands off” with users to keep costs down. Self-service models are cheaper to run, because they don't require as many paid people.

If you’ve adopted a product-led growth (PLG) mindset you'll love a self-service approach. If your pricing structure doesn’t support much hands-on help, self service must be a focus.

Your users might expect different if your product targets the mid-market or enterprise. Providing a simple, self-setup integration might actually be a negative attribute. They may want something from you that is hands-on.

There’s nothing wrong with integrations that require some work or get up and running. Just make sure your user profile and unit economics justify such an integration.

Consider what type of set up experience is right for your users. Consider that it might differ across different cohorts of your users.

What is the user’s technical sophistication?

Integration is technical. It’s about data and APIs, and these are technical concepts. It’s important to consider how technically capable your users are.

More tech-savvy users will be comfortable setting up integrations themselves. They'll be more comfortable with customizing them too. They'll probably expect this ability.

Less tech-savvy users will feel the opposite. They'll want it to be quick and easy.

User tech savviness should influence how flexible that self-setup experience will be. It should influence how you would structure projects for delivering complex integrations. It should influence how those integrations projects go once underway.

Getting this wrong will create pain for users. Getting this right will help you create a fantastic user experience.

Saying, “our users are technical” isn’t specific enough, either.

Instead, rate users’ comfort with specific concepts like APIs, XML or JSON data, and even coding. This will help you get more fine-tuned about the experience you create.

What are your categories of integrations? How do they differ?

Many B2B software companies provide dozens of integrations–sometimes hundreds! It's complicated treating each integration as a wholly unique animal. To make things less complex, think about how you categorize them.

Integration categories help you establish consistent practices for the integrations in your portfolio. It helps you to establish “another one of these” to simplify internal decision making.

The type of product (e.g. CRM, ERP, or CMS) is the most obvious categorization, but it’s not the only way to categorize. Consider categorizing by target persona, SMB vs enterprise, and functional similarities.

Categoirzation will help you generalize. For example, you might decide on rules like:

• You build self-setup integrations for CMS products
• You build project-based integrations for ERPs
• All SMB focused integrations must be use OAuth

This categorization also helps to create consistency for your users across like integrations. It makes it as easy as possible to switch. This helps to ensure that your product remains part of the tech stack.

No Integration Can Support Everything

One last consideration is more advice than a question. Integrations are the kind of project that can spin out of control.

APIs can often support a lot of different actions. Users can come up with all sorts of different requests. In a vacuum, people can be very creative.

But, no integration can or should support everything.

You will never provide an integration that provides exactly what every user wants. If you try, you’ll chase a never ending long tail of unique business requirements. You’ll invest far more into the work than is worth it.

There is a point where you say, “that’s enough.” Here, you should accept that you've supported enough functionality for most users.

It's how you prevent scope creep. It's how you avoid building one-off features. In the end it creates a better experience for that majority of users you can support.

Pillars of a Great Integration UX

A lot goes into creating a great integration user experience. There are small details that can make a big difference throughout the entire journey.

In the following section, we break down the best practices over three pillars. They define the important parts of your user's integration experience:

• Discovery - Helping users find the integrations they need/want
• Activation - Helping users set up and enable the integrations
• Operation - Helping users make use of the integrations over time

Discovery

What good is an integration if customers and prospects don’t know it exists?

Integrations are a perceived extension of your product. It’s important that your prospects and customers can find and learn about them. You should educate prospects and customers about your integrations in multiple ways.

B2B buyers spend an increasing amount of their vendor evaluation process online. This happens before talking to a sales rep.

It’s important to help potential users self-educate about each of your integrations. The best way to enable this experience is through a website-based integration marketplace.

Integrations are usually important to potential users. Your marketplace is likely to be one of your top 3 most viewed web assets. It may surprise you how effective it can be at converting visitors to qualified leads.

Your website marketplace also acts as an enablement tool for your customer-facing teams. It should be public facing, on your website.

Sales and Customer Success teams can use your marketplace to educate themselves. They can educate prospects and customers customers on your integrations, too.

This will help Sales close more deals. It'll help Customer Success increase product adoption sooner. It'll help to ensure top-tier customer satisfaction and retention rates.

But, what about users who are already paying customers?

An in-app marketplace is the most effective way to help users discover integrations. You should place this where your customers live every day, in your app.

With an in-app marketplace, integrations are one click away. This makes it super easy for customers to discover and adopt integrations.

Your goal is to bring the experience from your website marketplace into your app. It will help users who are paying customers see the integrations you provide. It will give them a clear path to install those integrations.

You might choose to build your own marketplace in-house. You might choose to use a third-party marketplace platform.

In either case, these are best practices you can follow to ensure a great user experience:

• Easy to Find - Include your website marketplace in your website's navigation. Include the in-app marketplace in the app's navigation.
• Content Consistency - Make sure content is consistent. Your website marketplace should mirror your in-app marketplace.
• Get Help From Partners - Enable your partners to manage their listing to reduce your team's work.
• Beautiful Design - Your marketplaces should be marketing-grade and align to your brand.
• Simple Marketplace Navigation - Provide categories, filters, and search. These make sense to your users and help them find the integrations they need.
• Helpful & Compelling Listing Pages - Include all information to your user. You want them to move forward without having to navigate off the listing page.
• Incorporate Media - Add screenshots, images, and videos to bring your listings to life.
• Convert Visitors - Have calls-to-action that send visitors into your install flow. You can also have them capture leads for you and/or your partner.
• Social Proof - Share testimonials on the listing pages. Allow customers to leave reviews. Consider pulling reviews in from sites like G2.com.
• Integrate - Connect your marketplaces with your existing tech stack. This will reduce manual work for your team and improve the customer experience.

Activation

Activating the integration is when your user goes through the setup process. It’s the bridges the users intention to an actual working integration.

Activation is probably the most critical pillar. It’s where you are most likely to lose the user if it isn't easy or clear how to complete activation.

Consider the following best practices for creating an effective “activation” user experience.

Transition from Discovery

The handoff from the Discovery pillar to the Activation pillar is critical. You want to make sure this experience is as seamless as possible. Even small points of friction can frustrate users enough that they give up.

Typically, the transition begins with clicking the call-to-action on your integration marketplace. This would be something like an "install" or "connect" button.

If this happened from your in-app marketplace, the user is probably already logged in. If it happened on a public-facing website marketplace, you’ll have to allow the user to log in. This might also require the user to sign up if they are new.

Without becoming a logged in user, they can’t set up the integration the rest of the way.

If your user starts from the public-facing website marketplace, it’s  best to use deep links. These direct the user to the integration's listing on your in-app marketplace.

When disrupting the flow for login or sign up, you’ll want to keep the following best practices in mind:

• Remember where they were going. Once they complete the required task (e.g. log in), you want to put them right back where they left off. Don’t make them find it again.
• Make the required task as quick and easy as possible. Don’t ask for more clicks or more information than required. Remember, you interrupted them.
• Measure fall-off. If you are losing users through this disruption, you need to understand why. Fix the problem!

Following login, the user will expect to flow to authentication & authorization. This step establishes that your app can talk to the other app on the user’s behalf.

After authenticating, the user should be able to configure the integration further. That is, if there are more options to configure.

If there's nothing to configure, they should be able to activate the integration.

Authentication, authorization, and configuration are technical terms. The next sections explain them further.

Authentication & Authorization

Authentication & authorization are two of the harder parts of building an integration. As a result, that complexity often seeps into the user’s experience.

Okta does a great job describing authentication and authorization and how they relate:

Authentication [is] a key. The lock on the door only grants access to someone with the correct key in much the same way that a system only grants access to users who have the correct credentials.Authorization [is] permissions. Once inside, the person has the authorization to access the kitchen and open the cupboard that holds the pet food. The person may not have permission to go into the bedroom for a quick nap.

For this section, the differences are not important, so we’re going to lump them together under the term “auth”. This is a common word people use when talking about them, anyway.

Auth allows the user to grants your product permission to talk to the integrated product. The user does it on their own behalf.

The user will do this many times for many different integrations. Creating a best practice auth experience is about creating consistency. You don't want each integration to feel like a new auth experience.

Auth is usually based on standards like username/password, API keys, and Oauth. You should create consistent experiences by standard. For example, all Oauth should work the same way.

You should also respect the terminology of the integrated app. For example, don't call it a "username" if the integrated app calls it "email" on their login screen.

Consider deprioritizing or simplifying any auth that falls outside of the standard approaches. Unique and uncommon auth can add a lot of complexity to an integration before the user even gets to start using it!

But, there's a catch!

While generally accepted auth standards exist, they are not always followed. Your goal should be to shield your users from that nuance. Instead, provide a consistent experience over top of auth for all integrations.

Remember, auth can be intimidating for non-technical users. If auth requires that you ask for API keys or tokens, non-technical users may not understand.

It’s a good practice to provide guidance for the user along the auth journey, so they know what you’re asking them for.

Giving instructions for “how to get your API key” from the external system is so valuable. It’s more work for you to maintain, but it smooths out friction for your user.

Configuration

Sometimes every user of an integration will use it in exactly the same way. Simple integrations like “publishinf a message to Slack” serve basic use cases. There isn’t much room for user-specific requirements. Often, this simplicity is not the case.

Most integrations offer some configuration beyond providing auth. This allows the user to tweak how the integration works to meet their unique needs.

Sometimes integrations must allow for or even need a large amount of configuration. When integrating to more complex products (e.g. ERPs and CRMs), it’s rarely possible to hardcode logic. You must ask the user to provide information.

Seek to understand how much configuration your users need. Understand how much they can handle. This is where a product- and user-experience mindset helps you get it right.

Usually a good place to start is the 80-20 rule. Most of the time 80% of an integration should be the same for every user of the integration. 20% should be configurable (within the bounds build into the integration) on a per user basis.

Customization

Configuration is about tweaking the integration within the bounds of the integration. You code in the configuration options.

Customization is about taking the pre-built integration as a starting point. It's about developing it further according to unique needs. When you customize, you fork the integration.

Customization is harder and higher risk than configuration. It’s harder to provide customizable integrations at scale. You risk creating a lot of technical debt and/or customer support challenges.

Often, teams offload customizing an integration to a third party solution integrator (SI). They will customizes the integration as a professional services project.

Customization doesn’t have to be something you outsource, through.

Customization requires you to put in place a strict discipline. You must manage the core integration functionality. Then, you must keep customized variations up to date.

This is usually difficult to do in low-code environments. Expect this only to work well with engineer-built and -managed integrations.

Engineers already have well-established practices and mature tools for dealing with such problems. It’s exactly the challenge they face when building complex software products. It's how you code with large, distributed teams.

Don’t assume you should provide customized integrations. This is definitely an “advanced” capability. But, if your users do need them, know that there are best practices to make it scalable.

Like with auth, sometimes configuration can be confusing or intimidating for users. After all, they are configuring an integration, which is by nature quite technical.

Provide instructions and context. Write them in a way that is easy to understand for your user. It will help them get the setup right.

Enable/Disable

The user has granted permission via auth. They have injected their unique needs via configuration. Last, they’ll need to control when the integration is flowing data.

In other words, they’ll need an on/off button!

The user must have the ability to control whether the integration is “doing stuff”. This should be separate from defining “what stuff it should do”.

This helps them with launching your product, the integrated product, and the integration. Simple integrations and complex ones need this feature!

It’s also important to recognize that bad things happen. APIs go down, bad data gets entered, and servers get hosed. Sometimes, you need to stop the data from flowing until someone sorts out the problem. It's like shutting off the water when a pipe is leaking.

Consider the user’s experience for enabling and disabling a flow. A simple toggle or button is plenty complex. The user needs to know if the integration is currently on or off. They need to know that that clicking the button (or whatever) will turn it off/on.

If you want to make the experience even better, show that data is flowing as soon as the user enables it. This helps to reinforce the message that everything is working.

Read more about how to show data flow in the “Operation” section.

Onboarding Help

Users will get confused. It doesn't matter how incredible your integration user experience is. Integration is hard, even for simple ones. This is especially true for non-technical users.

Consider how much help users will need and how they will want to receive that help. This should align with your overall support strategy. It might include documentation, chat support, phone support, and even onsite consultants. To your users, support for integrations should by like support for any other feature.

Inside your company, you do need to consider how integrations are a little different. You must help your support or onboarding teams understand the integration.

They will be the ones who must assist customers. If they have no knowledge of the integrated system, how will they help? If they don't know what the integration allows your product to do, how will they help?

You also have to consider the ROI of building this competency. You can’t make your entire support team an expert in every integration. You can't make them experts in every integrated system. It’s too hard and too expensive. You have to decide what's important.

How do you operationalize centers of excellence around those most important integrations? How do you distribute this knowledge? Then, how do you route your users to people who can help them best? Which ones will need the most support? Which ones should you invest most in?

Your integration user experience doesn’t stop at the edges of your product! Your user’s experience with support around your product also plays a huge part. This is also true with your product’s integrations.

Operation

Discovering and activating an integration is about connecting users with integrations. Discovering and activating doesn’t actually provide the value though. It leads the user to the value.

Until the user actually turns on the integration, they haven't achieved success. Nor have they until they use the integration to execute cross-product business processes. success.

Once they get to success, you want to keep them there! The user experience of operating the integration is as important, too.

Monitoring for Success & Failures

It’s one thing for a user to turn an integration on. It’s another to show to that user that the integration is active and doing what it’s supposed to.

Consider your users' needs and technical ability. Something as simple as a red light/green light indicator might be best. Often something that simple isn’t enough, especially if:

• The data moved by the integration is mission critical
• The integration and/or its configuration is complex
• The integration environment or underlying runtime is unstable
• One or both of the integrated systems is unstable
• Your user is technical and expects more

In any of these cases, you’ll want to consider providing more detail. You'll want to show your user info about the data that is moves through the integration.

Consider showing specific data records labeled with a business identifier. A business identifier is something like an order number or a customer number.

Show whether each record was successfully or unsuccessfully sync'd through the integration. For more technical users, consider showing logs or more specific technical information. Tie this info back to that identifier that the user understands.

Helping your user identify and deal with data failures is important. It's more important than the many times data successfully moves through the integration. It's how the user identifies and addresses exceptions.

But, you must consider balance. Showing too much detail can be overwhelming to the user. Showing too little can be unhelpful.

Responding to Failures

It’s important to surface failures, but then what is the user supposed to do?

An integration should help its users deal with failures. Users will want this done as quickly as possible.

Failures usually fall into one of these categories:

• An infrastructure failure (lack of CPU or memory, etc. in the integration environment)
• An endpoint API failure (one of the integrated systems is down)
• Data-related problems (a user does something that passes invalid data through the integration)

The user or someone supporting the user handles all these differently. Your contractual obligations may state that you have the handle them for the user.

When designing the user experience for handling failures, remember one thing. Your customer does not understand or care how complex or unique their integration is. They just want it to work 100% of the time.

Providing this never-failing integration is your problem. Just remember that this is the user's expectation.

Making it work within your user economics is your problem too. Consider your pricing model when designing how you support integrations. It’s hard to afford dedicated customer support if your product is very inexpensive.

You can create valuable cross-product experiences with your integrations. But, you must nail balancing these competing priorities.

Notifications

Very few users are going to actively “go find” what’s happening with the integration. Pushing relevant info to them helps get their attention only when it’s required.

We already discussed surfacing integration successes and failures in your product. You’ll also want to provide proactive notification to your users when failures occur.

Email notifications are a common way to handle this, because email is ubiquitous. However, you do run the risk of the user tuning out the emails or them caught in spam folders. People receive a lot of emails, after all.

You can also consider push notifications via mobile app or web browser, if it makes sense in your product.

SMS (text message) notifications might be appropriate, too. These are useful if it’s time-critical that certain users receive some notifications.

Pushing data to monitoring platforms is also useful for many users. Datadog and Dynatrace are common ones, but there are many.

Most of the time, you deliver notifications to alert about a failure. Your user might want you to notify for successes though, too. Usually this is for exceptions, like particularly large or high value data objects.

It’s technically possible to alert on every success. Most of the time that is too noisy to be useful.

Technical Support & Service Level Agreements

How your team supports integrations is also a huge part of the user's experience.

That support team's first job is to ensure the integration gets configured correctly. They also help the user keep the live integration healthy. This may even be a service level or support agreement obligation.

You must consider how support obligations align with user expectations. You also need to reconcile this with your own unit economics.

However, support can be an excellent way to enhance your user’s experience. It can help you stand out against your competition.

Other Things to Consider

The following are more things to consider about the integration user experience.

Handling API Changes

Most of the time an integration is a bridge between two APIs: your API and the external, integrated system’s API.

You must help users navigate those APIs changes. A high quality integration experience requires it.

(If one or both sides isn’t literally an API, that’s ok. This all still applies.)

Just like the rest of the software, APIs are prone to change. This shouldn’t happen often, and APIs shouldn’t implement breaking changes. But, the fact is, anything and everything happens in the wild. You should prepare for it.

Consider your process for monitoring API changes and rolling out updates.

Consider how this fits into your support obligations with customers.

Focus on making this complex problem into a simple one for your users. Then tell them about how you ease the pain!

Measuring Usage & Business Value

Well-built integrations provide a lot of value for your users. That value often goes unmeasured and unmentioned.

Users hate when integrations fail, but rarely celebrate when they work well. Consider how to surface the value your integration provides. Remind your user how important it is to them.

The particular measure of business value will vary by integration. Sometimes it’s easy to calculate (e.g. total dollar value of orders passed through an integration). Sometimes you have to get a little more creative.

Always try to get to a dollar amount to describe business value, if you can. Don’t worry about creating a perfect measurement. Something generally correct and achievable is good enough.

Then, share that with users without bragging or being too self-congratulatory.

You're adding a lot of value with a well-functioning integration. It's okay to remind your user of that.

Monetization

To what extent, if at all, you monetize your integrations also plays a part in your user’s experience.

For one thing, it might put up a gate for the user if they need approvals to activate something paid. At the very least it ups the ante on your obligation to deliver quality.

Monetizing integrations is a topic for a post on its own (which is coming). For now, consider that it will have an impact on your user and their experience.

‍