Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cello.so/llms.txt

Use this file to discover all available pages before exploring further.

By default, tokens are long-lived and do not expire. However, you can choose to have your tokens expire every 24 hours for enhanced security. In that case, Cello considers tokens created more than 24 hours ago expired and therefore invalid. You can deal with the timing yourself, but the preferred way is to handle onTokenExpiring and onTokenExpired events by assigning your callbacks via the boot command. We provide special updateToken SDK command for that.

​
updateToken(token)

Updates the token that the library is using. Should usually be called after Cello has indicated the token is starting to expire with the onTokenExpiring callback. 
window.Cello("updateToken", newToken);
To provide a seamless experience for the user, the implementation should mint a new token before the previous token expires. To help customers detect these situations and avoid relying on custom timers, Cello provides two callback events that a developer can add to the cello.boot command. 
window.cello = window.cello || { cmd: [] };

window.cello.cmd.push(async function (cello) {
  try {
    await cello.boot({
      productId: 'CELLO_PRODUCT_ID',
      token: 'REPLACE_ME',
      language: "en",
      productUserDetails: {
        firstName:'Bob',
        lastName:'Bobsky',
        fullName:'Bob B Bobsky',
        email: 'bob@gmail.com'
      }, 
      onTokenExpiring: ()=> {
        // Handle token refresh
      }
    });
  } catch (error) {
    console.error("Failed to boot cello:", error);
    // Handle the error appropriately
  }
});

​
onTokenExpiring

This callback is called when Cello detects that the token in use is going to expire in 5 minutes. This should leave enough time to mint a new token and register it with Cello.

​
onTokenExpired

It may still happen that the time to expiration has passed - for example, when a user has been offline and reopens their laptop. In that case, Cello triggers the onTokenExpired callback. In most cases, a developer should assign both of the above events and implement the same routines there. The separation is meant for special cases when developers want to do different things (like logging) depending on the situation.

​
Example of the whole flow

// ... other code ...
   window.cello.cmd.push((cello) => cello.boot({
      productId: 'YOUR_PRODUCT_ID',
     ....
      onTokenExpiring: async () => {
     		console.log("Token expiring, updating token");
     
     		// this line depends on how the token creation is implemented by the customer
     		const newToken = await customerSpecificTokenCreationRoutine();
     
          try {
            await window.Cello("updateToken", newToken);
          } catch (error) {
            console.log('error, updating token');
          }
        });
      },
// ... other code ...
CallbackTypeDescription
onTokenExpiring: () => { your code },functionCallback event triggered when the used token is about to expire in a few minutes. You would implement getting a new token in this callback.
onTokenExpired: () => { your code },functionCallback event triggered when the used token has expired. You would implement getting a new token in this callback.

​
Cello for iOS

To provide a seamless experience for the user of iOS app, the implementation should mint a new token before the previous token expires. To help customers detect these situations and not need to rely on custom timers, Cello provides two events which you can listen to for updates by observing an NSNotification.

​
CelloTokenAboutToExpire

NotificationCenter.default.addObserver(forName: .CelloTokenAboutToExpire,
                                       object: nil, queue: .main) { [] _ in
											print("Expiring")
}
This event is triggered, when Cello detects that the used token is going to expire in 5 minutes. This should leave enough time to mint a new token and register it with Cello.

​
CelloTokenHasExpired

It may still happen that the time to expiration has passed, for example, when a user has been offline and reopens their laptop. In that case, Cello triggers the CelloTokenHasExpired event. 
NotificationCenter.default.addObserver(forName: .CelloTokenHasExpired,
                                       object: nil, queue: .main) { [] _ in
											print("Expired")
}
In most cases, a developer should assign both of the above events and implement the same routines there. The separation is meant for special cases when developers want to do different things (like logging) depending on the situation.

​
Cello for Android

To provide a seamless experience for the user, the implementation should mint a new token before the previous token expires. To help customers detect these situations and not need to rely on custom timers, Cello provides two events which you can listen to for updates.

​
addTokenAboutToExpireListener

Cello.client().addTokenAboutToExpireListener(listener)

Cello.client().addTokenAboutToExpireListener(listener);
This event is triggered, when Cello detects that the used token is going to expire in 5 minutes. This should leave enough time to mint a new token and register it with Cello.

​
addTokenExpiredListener

It may still happen that the time to expiration has passed, for example, when a user has been offline and reopens their laptop. In that case, Cello triggers the TokenHasExpired event. 
Cello.client().addTokenExpiredListener(listener)

Cello.client().addTokenExpiredListener(listener);
In most cases, a developer should assign both of the above events and implement the same routines there. The separation is meant for special cases when developers want to do different things (like logging) depending on the situation.

​
Cello for React Native

To provide a seamless experience for the user, the implementation should mint a new token before the previous token expires. To help customers detect these situations and not need to rely on custom timers, Cello provides two events which you can listen to for updates.

​
tokenAboutToExpire

import Cello, { CelloEvents } from '@getcello/cello-react-native';

Cello.addListener(CelloEvents.tokenAboutToExpire, () => {
  console.log('about to expire');
});
This event is triggered, when Cello detects that the used token is going to expire in 5 minutes. This should leave enough time to mint a new token and register it with Cello.

​
tokenHasExpired

It may still happen that the time to expiration has passed, for example, when a user has been offline and reopens their app. In that case, Cello triggers the tokenAboutToExpire event. 
import Cello, { CelloEvents } from '@getcello/cello-react-native';

Cello.addListener(CelloEvents.tokenHasExpired, () => {
  console.log('token expired');
});
In most cases, a developer should assign both of the above events and implement the same routines there. The separation is meant for special cases when developers want to do different things (like logging) depending on the situation.