How to design third party integrations if you’re an analyst

Howdy-ho, Kyle!

Let’s discuss a question that is pretty controversial for a business analyst: how much should you really know about development? Say, to analyze or pick a way to interact with a third-party system when designing a feature. After all, developers, a priori, are better versed in the tools they have — why ask an amateur a business analyst?

Outsourced development often involves dealing with suddenly emerging tasks; teams work on different projects — sometimes simultaneously. That’s why they face the choice of integrations pretty often: in my experience, at least once every two months.

What I mean by third-party integrations is using APIs or SDKs to enhance the functionality of a service, introduce process automation, and address business objectives.

When you work according to SCRUM, technical specs are put together a sprint or two before they are developed. By the time the developers start decomposing a feature, it should already be designed according to specifics of an SDK along with the detailed integrations and specifics of a product and business objective. Leads can help clear up any doubts, that’s for sure. But it doesn’t negate the fact that the top-level analysis of third party systems and the choice of integrations are the job of an analyst.

Hi! I’m Diana Statsura, and I specialize in mobile analytics at Surf. Based on real-world cases, I’ll show you what situations you can run into while dealing with third-party integrations and share some tips that help me and my colleagues.

Want to stay on top of app development trends and know how to create apps millions of people love?

Follow Surf on Twitter!

Responsibilities of an analyst

Anyhow, let’s talk about the tasks that analysts have on projects and their role in the teams. What if it’s in the default job description of an analyst to analyze an SDK, design integrations and program programs, and I’m here rambling for no reason.

I keep an eye on the job market, and I’m also a person who’s tried explaining what I do to my parents. I’d say that my job isn’t as well-defined as, say, that of developers (even though there are so many kinds as well), and includes pretty big bucket terms. Not everyone clearly gets what analysts are and what role they play in product development. Some even try to prove that no one needs an analyst on a project.

Our roles vary and depend on the project, team, and company. Despite the fact that the lines are blurred, there’s analytics on every project. In our context, it includes:

• business analysis,
• systems analysis,
• product analysis. If you want to learn more about the product approach and product analysis at Surf.

Large-scale, complex projects absolutely need analytics: it helps figure out project goals and align processes the right way. That’s why it’s the analyst who sets the direction in which a project is growing.

Besides the basic tasks detailed for each job opening, analysts are also responsible for the following:

• handling backlog,
• market analysis at the project onset,
• the choice of development tools that best address a challenge in the context of a feature, etc.

What’s the difference between leaving developers to decide on integrations and making analysts do it for them?

There are two ways you can go about picking an integration: either let developers figure out the feature by themselves or let an analyst examine it first.

Option one: developers figure out the feature by themselves

Developers pick the implementation they find easiest and most convenient. But:

• They don’t always come from a place of choosing the most user-friendly one or addressing the needs of a client.
• Sure, the feature will be implemented, but it won’t align with business objectives. Say, your client wants to add extra logic to the project. Not all SDKs can provide that. In their search, developers will primarily look for something convenient and stable, which might lead to them overlooking the logic the business was expecting to get. In the end, the client won’t be happy: you didn’t do what they wanted.
• Developers on different platforms may initially pick different integrations: for example, the Android team will pick an SDK, while the iOS team will decide to use an API. Or they’ll both use SDKs — but different ones. In this case they’ll need a third party to settle the debate anyway.

Option two: the feature is first examined by an analyst.

An analyst examines client and user requirements. What that gives is:

• You’re focused on the results needed: even if something is pretty hard to do, developers won’t be able to skip it and say “It could be done faster and easier if you take away this logic” or “No way that’s impossible”. This is the part where developers boo me out :(
• Quality on another level: at least three people work on one feature, which makes it more likely that no case is left behind.
• A choice of a unified solution that suits both platforms at the same time. Besides, you get a unified implementation.

How to pick a third party implementation depending on a feature

Let’s go over the options again:

• System interaction via an API.
• An SDK.
• A mobile app accesses the backend, which, in turn, interacts with the system (which basically equals the first option).

For my example, I chose three features:

• digital receipts,
• push notifications,
• chat.

They’re all different in terms of complexity and, as they were going through development, I’ve run into different business processes (think “problems”:)).

To choose an implementation, you have to identify the business objective your client wants to address with this feature. To do that, analysts discuss business requirements with their clients and, as a result, provide developers with descriptions of the functionalities required.

Third-party integration analysis depends a lot on their specifics. There’s no clear guideline on how to describe an integration, but here is some general advice:

• Clearly state a business objective and base your choice of implementation on that.
• Keep in mind the system requirements, i.e., whether the offered functionality is enough. For example, if your context is dividing push notifications into channels.
• Consult with your team every step of the way: from the choice of an SDK to the means of implementing a feature. For instance, do we implement functionality in a custom way or use SDK methods?
• Double check if the client or the team need server interactions and what part of the functionality will be out in the frontend or the backend.
• Look back on what other projects and teams have experienced. Sounds like a “do what’s right, don’t do what’s wrong” situation, but it’s actually useful. In our company, for instance, we share project experience and rely on the knowledge of our colleagues who’ve already dealt with similar features.

Example 1. Digital receipts

This case will haunt my nightmares is my favorite. The feature turned out to be complicated both in terms of analytics and development. We had to go through numerous conditions together with the developers and find the best implementation.

One of the most challenging aspects is getting the conditions of the third party system interaction without directly interacting with it. All data was transferred through the backend.

Let’s look at some examples.

Business objective. Implement a functionality enabling digital receipts in a mobile app so that a user can choose a digital receipt instead of a paper one.

Interaction with the loyalty management platform that enables digital receipts was mediated by the server. Sounds like everything’s fine: part of the logic is run by the backend, and we don’t have as much work to do. In fact, it was more like working with your eyes shut because all the requirements for integration came to us in bits and pieces based on what the backend team was saying.

It’s pretty obvious that, in order to enable digital receipts, you have to pass email in the endpoint and receive HTTP 200 OK in the reply.

But here are a few pitfalls:

• A user may only have one email attached to the account in the system. That’s where all the receipts will come to.
• If there’s an email already attached to the account, users can’t specify another one.
• If the app shares the backend with a website, you need to listen to the status of the feature: users have multiple pathways to enable or disable the digital receipts.
• Digital receipts are only available to users with a loyalty card attached.
• You need to check whether users have loyalty cards.
• If they don’t, you have to lead users through the flow of creating a new loyalty card.

To identify business requirements, you must first analyze the way a platform works as well as interactions within the “mobile app — server — third party platform” chain. By analyzing that, you will get a better understanding of what information a mobile app should send and where you could find it.

To enable digital receipts, you need the following logic:

• Check if the loyalty card is available to identify a user in the system that enables digital receipts.
• Define the way the app gets access to the email that the checks will be bound to.
• Next, pass the loyalty card number or the email directly to the platform or the server, which, in turn, will pass it to the platform.

A mini case inside the case

And now — the real thing. As I was saying, our mobile app didn’t directly interact with the Loymax loyalty system: all the data was proxied by the server.

As a result, at the demo we had learned that email forwarded to the third-party system needs to be confirmed. To meet the extra requirement, we had to reconsider the already complicated logic and postpone the release for two weeks to get the feature done.

What could we have done to avoid that? Have a broader perspective, do an extra analysis of the interaction logic and try not to rely on the backend completely.

Example 2. Push notifications

In this one, let’s have a closer look at what affects the choice of an SDK.

Push notifications are short text messages that appear on the screen of a user device. What it does is give some important information: new special offers, order status, account transactions, etc.

To set a list of requirements for an implementation, you have to know whether you need some of the following:

• Dividing push notifications into channels — these determine what share of users receives a notification. It’s a user segmentation tool used for mailouts and to configure transaction push notifications.
• Configuring special offers for users.
• Switching the notifications on and off in the app settings. Spoiler: it’s a must! Otherwise, the app gets annoyingly persistent and not user friendly at all — such apps must be tossed out of the market :angry as fuk:

When we initially designed the feature, we were planning to use the SDK suggested by the client. The documents we analyzed seemed to match the functionality available in the SDK (said not by a man, but by a boy).

I must admit, that was my first analysis of an SDK and feature design with it: I made a lot of mistakes.

• I was mostly reading the documentation, not taking a good look at the features available.
• I designed a feature and wrote technical specs without consulting the developers.
• I first dived into SDK integration and only then started to analyze the functionality. Hence, I looked at the implementation from a pretty narrow perspective.

The team, in turn, didn’t take a closer look at the feature as well and overlooked the implementation details. It turned out:

• Implementing some of the functionality promised a wad of hydra code and testing complications. For example, the SDK gave no chance to disable push notifications completely.
• The SDK managers took several weeks to reply to our questions (what a life…).

In the end, we had to give up on that SDK even though most of our work had already been done. Of course, when we looked for an alternative SDK, we didn’t make the same mistakes. We made new ones (jk).

Based on my subjective experience, I’ve worked out a list of primary criteria to toss out the SDKs that don’t fit. A good SDK:

• Is thoroughly documented.
• Integrates in a way that’s easy to comprehend.
• Has clear methods, such as, descriptions of parameters that split push notifications into channels.
• Platform managers are quick to reply (not 2–3 days), give clear answers as well as access to a user profile and help configure that.

At this point, most SDKs fall off. Next, you need a deeper analysis and, of course, to run it all by your team.

For example, to pick another SDK for push notifications, we also looked for:

• Thoroughly described methods.
• Well-organized user profile.
• Push testing capability.
• Push configurations available in the app:
• Disable notifications in the mobile app.
• Partially enable and disable notifications (i.e. enable and disable specific channels).
• Competent and quick managers: without them, you can not, at the very least, configure a user profile.

Example 3. In-app chat

This example illustrates how important it is to gather business requirements. By doing so, you’ll find it easier to pick the implementation and define the scope of work based on the logic requirements.

The client’s business objective: an e-commerce app needs a chat to help users contact support any time they need it.

A support chat is an absolute must have for a banking app and is worth the expense. A custom support chat in an e-commerce app, however, may cost an arm and a leg and remain purely decorative.

Users will hardly feel the urge to contact the app’s support if they can’t order a new sweatshirt or a squeaky ball. Most likely, the chat simply shows that the client is focused on customers: “You’ll get help if something goes wrong with your order.” Chat features and quick response are not the priority in this case: the client hardly wants to pay extra for custom features.

On the other hand, if the client wants a cheap chat, there are three ways you can do that:

• an SDK,
• a third-party API,
• redirecting users to chats in messengers.

The client initially wanted to build the chat with an SDK. We’ve examined the options and found some issues with them:

• The support ignored our questions and took weeks to answer.
• Odd integration and messy documentation.
• Ill-organized API. For example, the SDK we were supposed to use for the chat didn’t have a separate endpoint to receive a list of chats. Instead, you had to call a list of tickets and filter them according to their user_id (I know you didn’t get that — neither did we).
• Bad code and a great chance of crushing (and I’m not talking about all of a sudden locking your eyes with a cutie pie while you’re walking down the street and realizing it’s your destiny).

Initially, the team just wanted to find another SDK, but… finding a good SDK with well written code that doesn’t crash and quick or at least functioning support turned out to be pretty hard.

That’s why, based on the business objectives, deadlines, costs, and implementations available, we opted to redirect users to messengers. That reduced the amount of work the team did and the time spent on the feature.

Analysts can identify some of the issues if they analyze the documentation and discuss implementations available with system managers. However, some issues may stay out of their picture — at least because they’re not looking at code. For instance, in this case, the person drawing our attention to the bad code and high crash risk was our team lead.

That’s why it’s crucial to involve developers in the process and run it by them at all stages of your SDK analysis. It might turn out you’re inventing the wheel at the expense of your client (enormous expense). Sometimes, the simplest implementation is the best fit.

Writing technical specs

So, we’ve covered the tools. Now let’s think about what should be reflected in the specs.

If an SDK documentation or a description of a third-party API is a general guideline, technical specs are what must be done exactly to tackle a task. Analysts have to describe the task to developers in as much detail as possible so that the implementation meets the expectations.

The key points affecting the implementation of a feature are:

• What methods of an SDK or a third-party API to use for an integration.
• What parameters to pass.
• Whether or not keys need to be generated to connect (to an SDK).
• How to get the information provided by a platform to display it in the app.
• Add links to a more detailed description (e.g., methods used or how to generate keys) if it has more exhaustive information that shouldn’t be included in the specs.
• Done! You’re awesome.

Push-wise you’ll need to write:

• how to generate keys.
• how to connect to the system itself.
• what option to choose when sending events: through server or via an SDK.
• how to divide them into channels.
• data.payload.

Based on real-life cases, I wanted to show you what analysts are responsible for and how deep they need to dive into their projects and development.

Analysts don’t have to climb under the hood of an SDK and analyze code. They need to think carefully when choosing development tools and keep various factors in mind. All they need for that is standard skills:

• being able to communicate with the team and the client,
• understanding technical documentation,
• critical analysis of this or that implementation,
• understanding product values and business logic.

Thanks for reading up to this point, and I’ll see you around! Peace out to all the cutie pies out there!