SDK

This is an SDK that is available in the Celcomdigi Super App. It can be imported and used by Mini App developers to provide a seamless experience for the users.

Public Interface

SDK exposes a set of React hooks and components that can be used by Mini App developers. These helpers are nothing more but a tiny wrapper on top of useContext to make experience working with the SDK nicer for end developers.

The actual context is provided by the SDK Runtime, which is further explained in the next section.

There are three APIs available out of the box, in the POC:

• permissions: managing and requesting permissions by mini apps to read sensitive data
• user: user module that demonstrates use of permissions, together with reading the data
• payments: user module that initiates the payment flow

You can learn more about them here.

The SDK also comes with a UI components that can be used by mini apps to provide a seamless experience for the users. You can learn more about them here.

SDK Runtime

SDK requires runtime to be provided by the host app. It is a set of functions that SDK expects to be available in the React context. These functions are used to retrieve data requested by the SDK, and perform actions accordingly.

![NOTE] In order to create sandbox environment that is safe from production, provide alterative version of the SDK runtime that does not rely on the actual data. Check the next section for more information on how to provide the runtime.

Example Implementation

Here is a step-by-step guide on how to implement a new API in the SDK, as well as to provide its runtime implementation inside the host app.

Step 1. Create a new SDK api

Navigate to api and create a dedicated file for your new API. For example, if you want to add payments capability, consider using payments.ts as a name.

Step 2. Define shape of the API

export type Permissions = {
  granted: (permission: string) => boolean
  request: (permission: string | string[]) => Promise<boolean>
  revoke: (permission: string) => void
}

Step 3. Create React Context

export const Permissions = createContext<Permissions>({
  granted: () => {
    throw new Error('PermissionContext not provided')
  },
  request: () => {
    throw new Error('PermissionContext not provided')
  },
  revoke: () => {
    throw new Error('PermissionContext not provided')
  },
})

Create and export a new React Context.

![NOTE] It is a good practice to provide default implementation and throw an Error. In that case, developers will get an early feedback that something is wrong, as actual context (as provided by the host) is missing in the React tree. Typically, this should never happen, provided all steps in this guide were completed.

Step 4. Provide a higher-order hook for developers

export const usePermissions = () => {
  return useContext(Permissions)
}

This step is optional, but we decided to abstract away this implementation detail as a part of the POC.

Step 5. Extend SDKRuntime with your new API

export function SDKRuntimeProvider({
  children,
  permissions,
  user,
}: PropsWithChildren<{ permissions: Permissions; user: User }>) {
  return (
    <Permissions.Provider value={permissions}>
      <User.Provider value={user}>{children}</User.Provider>
    </Permissions.Provider>
  )
}

Make sure to include your Provider component (in case of this example, it is Permissions.Provider) in the SDKRuntimeProvider. The SDKRuntimeProvider is rendered by the host, or any environment that is compatible with your mini apps (e.g. your sandbox, if you have one).

Step 6. Create actual implementation in the Host

Depending on your business requirements, implement Permissions module according to the interface defined earlier.

Step 7. Include your implementation in the SDKRuntimeProvider

 <SDKRuntimeProvider permissions={permissions} user={user}>
  {children}
</SDKRuntimeProvider>

If you have followed the guide, TypeScript will tell you right away that new API must be provided in the runtime. If you have implemented all the APIs correctly, there should be no errors and everything should work just fine.

Available modules

Permissions

• Ask for permission
• Check if permission is granted
• Revoke permission

User

• Login
• Logout

Billing

• Charge

Available components

• Button
• Heading
• Container

FAQs

Why there is SDK (a separate package) and Runtime (defined in the host), instead of just a single package?

There are a few reasons for this decision decision:

Decoupling: By putting runtime in the host, there can be different versions of the runtime, depending on the host (e.g. production. sandbox). This makes it easy to open your codebase to the public (there can be a fake runtime that does not depend on any of your internal services and business logic), as well as perform tests in isolation.

Security: Mini-apps don't have access to actual code responsible for loading, managing sensitive data and interacting with your application. It is similar to a precompiled code, where headers (public interface) are readable, but actual implementation is a hidden detail. That split makes it much easier to control the communication and enforce that only approved actions can be performed.