Tawasal Mini Apps SDK Documentation

This documentation provides comprehensive guidance on handling user data and utilizing the available methods (hooks) in Tawasal Mini Apps.

User Data Access

Tawasal Mini Apps can access user data through two main sources: the cookie.tawasal or via window.getUser() (without userToken). This data includes:

• userId: number: The unique identifier of the user.
• userToken: string: A secure token for session authentication.
• userNickname?: string: A nickname assigned to the user.
• firstName?: string: The user’s first name.
• lastName?: string: The user’s last name.
• platform: 'ios' | 'android': The operating system of the user’s device.
• version: string: The version of the Tawasal app, formatted as “x.y.z”.
• language: string: The language code, such as “en” or “ar”, representing the user’s preferred language.

Hooks

Tawasal Web SDK offers a range of methods — hooks — for deeper platform integration:

• getUser(callback: ResponseOrValue): Retrieves the current user’s details.
• getUserPhoto(callback: ResponseOrValue): Fetches the current user’s photo.
• getPhoneNumber(reason: string, callback: ResponseOrValue): Retrieves the user’s phone number with consent.

If applicable, you can provide promise resolver which receive value from Tawasal SuperApp.

import { getPhoneNumber } from "@tawasal/web";
 
getPhoneNumber("Provide title, so user will know why they should allow you their phone")
  .then((value) => {
    form.submit({ phone: value });
  });

And many others. Check them out.

Handling User Tokens

To verify the authenticity of a userToken, you can use the following function to check its signature. This approach is recommended for non-critical moments to avoid latency in user verification through the Verify User. The publicKey required for this verification can be obtained from the Dev Management.

JavaScript Example

import crypto from 'crypto';
 
function verifyTawasalUser(
  publicKey: string,
  userId: number,
  signatureBase64: string,
  authKeyId: string,
  deviceToken: string
): boolean {
  const signature = Buffer.from(signatureBase64, "base64");
  const verifier = crypto.createVerify("sha256WithRSAEncryption");
 
  verifier.update(Buffer.from(String(userId)));
  verifier.update(Buffer.from(authKeyId));
  verifier.update(Buffer.from(deviceToken, "utf8"));
 
  return verifier.verify(publicKey, signature);
}
 
// Usage
function handler(req: Request) {
  // userToken and userId provided in cookie.tawasal represented as base64
  const tawasal = atob(req.cookies.get('tawasal'));
  const { userId, userToken } = tawasal;
  const [signature, authKeyId, deviceToken] = userToken.split(":");
 
  const isVerified = verifyTawasalUser(
    publicKey, // obtain in Dev Management
    userId,
    signature,
    authKeyId,
    deviceToken
  );
 
  if (isVerified) {
    // do your thing
  }
}

This code allows for efficient, client-side verification of the userToken’s authenticity, reducing server-side dependency for quicker operations.