> ## Documentation Index
> Fetch the complete documentation index at: https://docs.traza.com.au/llms.txt
> Use this file to discover all available pages before exploring further.

# Update FCM Token Usage

> Updates the lastUsed timestamp for an FCM token. Can be called periodically to track active devices.

## Overview

Updates the `lastUsed` timestamp for an FCM token. This endpoint can be called periodically to track which devices are actively being used, enabling better token lifecycle management.

## Use Cases

* **Activity Tracking**: Monitor which devices are actively in use
* **Token Cleanup**: Identify stale tokens that haven't been used in a while
* **Analytics**: Track user engagement across multiple devices
* **Token Management**: Maintain accurate device activity records

## When to Call

This endpoint is **optional** but recommended for:

* App launch (update token usage on startup)
* Periodic background tasks (e.g., once per day)
* After receiving push notifications (device is active)

<Info>
  This endpoint is not required for basic FCM functionality. Registration and
  removal are sufficient for most use cases.
</Info>

## Example Usage

### Basic Usage

```typescript theme={null}
import * as Device from "expo-device";

// Update token usage on app startup
async function updateTokenUsage() {
  await fetch("/api/notifications/update-fcm-token-usage", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      deviceId: Device.deviceId,
    }),
  });
}
```

### Using React Hook

```typescript theme={null}
import { useUpdateFCMTokenUsage } from '@/hooks/notifications/useFCMTokenRegistration';
import { useEffect } from 'react';

function App() {
  const { mutate: updateUsage } = useUpdateFCMTokenUsage();

  useEffect(() => {
    // Update usage on app mount
    updateUsage(Device.deviceId);
  }, []);

  return <YourApp />;
}
```

### Periodic Updates

```typescript theme={null}
import { useEffect } from "react";
import { AppState } from "react-native";

function useTokenUsageTracking(deviceId: string) {
  const { mutate: updateUsage } = useUpdateFCMTokenUsage();

  useEffect(() => {
    // Update when app comes to foreground
    const subscription = AppState.addEventListener("change", (nextAppState) => {
      if (nextAppState === "active") {
        updateUsage(deviceId);
      }
    });

    return () => subscription.remove();
  }, [deviceId, updateUsage]);
}
```

## Behavior

When token usage is updated:

1. Only the `lastUsed` timestamp is modified
2. Token itself and other metadata remain unchanged
3. Operation is idempotent - safe to call frequently
4. Fails silently if token doesn't exist (returns success anyway)

## Future Use Cases

The `lastUsed` timestamp can be used for:

* **Automatic Cleanup**: Remove tokens not used in 90+ days
* **Analytics Dashboard**: Show active devices per user
* **Security Monitoring**: Detect unusual device activity
* **User Notifications**: Alert users about unrecognized devices

## Related Endpoints

* [Register FCM Token](/engineering/apis/notifications/register-fcm-token) - Register device for notifications
* [Remove FCM Token](/engineering/apis/notifications/remove-fcm-token) - Remove token on logout

## See Also

* [FCM Push Notifications Guide](/engineering/notifications/fcm-push-notifications) - Complete implementation guide
* [Token Management Best Practices](/engineering/notifications/fcm-architecture-diagram) - Token lifecycle documentation


## OpenAPI

````yaml POST /notifications/update-fcm-token-usage
openapi: 3.1.0
info:
  title: Tatu API
  description: API documentation for Tatu's booking and artist management system
  version: 1.0.0
servers:
  - url: http://localhost:3000/api
    description: Development server
security: []
paths:
  /notifications/update-fcm-token-usage:
    post:
      summary: Update FCM Token Usage
      description: >-
        Updates the lastUsed timestamp for an FCM token. Can be called
        periodically to track active devices.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFCMTokenUsageRequest'
      responses:
        '200':
          description: FCM token usage updated successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - message
                properties:
                  success:
                    type: boolean
                    description: Whether the operation was successful
                    example: true
                  message:
                    type: string
                    description: Success message
                    example: FCM token usage updated successfully
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    UpdateFCMTokenUsageRequest:
      type: object
      required:
        - deviceId
      properties:
        deviceId:
          type: string
          description: Unique identifier for the device to update
          example: device_abc123
    Error:
      type: object
      required:
        - message
      properties:
        message:
          type: string

````