FNO SDK

SDK JavaScript/TypeScript pour intégrer une carte 3D interactive propulsée par Unity WebGL dans vos applications web.

Table des matières

• Installation
• Démarrage rapide
• Configuration
• API Reference
  • SDK Principal
  • Camera Service
  • Asset Service
  • Pathfinding Service
  • Floor Service
  • Heatmap Service
  • User Service
  • UI Service
  • Metadata Service
• Système d'événements
• Architecture
• Développement
• Prérequis navigateur

Installation

npm install fno-sdk

Démarrage rapide

import Sdk from 'fno-sdk';

// Ces données sont disponibles dans notre backoffice après création de votre compte
const token = "{token}";
const tenant = "{tenant}";
const mapId = "{mapId}";

// ID du canvas HTML où afficher la carte 3D
const canvasId = "{canvasId}";

// Créer une instance du SDK
const sdk = new Sdk();

// Configuration des credentials
sdk.setTokenAndTenant(token, tenant);

// Initialisation du moteur Unity
sdk.initEngine(canvasId).then(() => {
    // Chargement d'une carte
    sdk.loadMap(mapId).then(() => {
        // La carte est prête, utilisez les services
        sdk.camera.zoomIn();
    });
});

Intégration HTML

Le SDK nécessite un élément canvas pour le rendu 3D :

<div id="map-container">
    <canvas id="unity-canvas"></canvas>
</div>

// Spécifier l'ID du canvas
sdk.initEngine('unity-canvas');

// Afficher le player dans un conteneur
sdk.showPlayer('map-container');

Configuration

Configuration par défaut

Le SDK utilise des URLs par défaut pour le stockage et l'API :

• Storage: https://storagefnodev.blob.core.windows.net/sdk/webgl/1.1.10/
• API: https://api.prod.findnorder.com/

Configuration personnalisée

sdk.setConfig({
    storageUrl: 'https://custom-storage.com/sdk/',
    baseUrlApi: 'https://custom-api.com/',
    unitySourceConfig: {
        dataUrl: 'custom/path/Build.data',
        frameworkUrl: 'custom/path/Build.framework.js',
        codeUrl: 'custom/path/Build.wasm',
        streamingAssetsUrl: 'custom/StreamingAssets',
        companyName: 'MyCompany',
        productName: 'MyMap',
        productVersion: '1.0.0'
    }
});

API Reference

SDK Principal

Méthodes de cycle de vie

| Méthode | Description | |---------|-------------| | initEngine(canvasClass?: string) | Initialise le moteur Unity WebGL | | loadMap(mapId: string) | Charge une carte 3D | | destroy() | Décharge la carte actuelle | | quitApplication() | Arrête complètement le SDK | | hidePlayer() | Masque le canvas | | showPlayer(destinationId: string) | Affiche le canvas dans l'élément cible |

Méthodes d'état

| Méthode | Description | |---------|-------------| | getCurrentState() | Retourne l'état actuel (waitingEngineInit, waitingMapInit, ready) | | getMapId() | Retourne l'ID de la carte chargée |

Camera Service

Accessible via sdk.camera

// Zoom
sdk.camera.setZoom(1.5);
sdk.camera.zoomIn();
sdk.camera.zoomOut();
sdk.camera.resetZoom();
sdk.camera.getZoom();

// Position
sdk.camera.resetCamera();
sdk.camera.zoomOnEntity('entity-id');

// Mode de caméra (2D/3D)
sdk.camera.setCameraType(CameraMode.TwoD);
sdk.camera.setCameraType(CameraMode.ThreeD);

Asset Service

Accessible via sdk.asset

Mise en surbrillance

// Asset unique
sdk.asset.setHighlightAssetById('asset-id', true);

// Plusieurs assets avec couleur personnalisée
sdk.asset.setHighlightAssetByIds(['id1', 'id2'], true, '#FF0000');

// Effacer les surbrillances
sdk.asset.clearHighlights();

Récupération de données

// Par ID
const asset = await sdk.asset.getById('asset-id');

// Tous les assets
const assets = await sdk.asset.getAll();

// Par codes de localisation
const data = await sdk.asset.getAssetDataByLocationCodes(['CODE1', 'CODE2']);

Événements

sdk.asset.registerOnSelectAsset((event) => {
    console.log('Asset sélectionné:', event);
}, 'mon-tag');

sdk.asset.registerOnHoverAsset((event) => {
    console.log('Survol:', event);
}, 'mon-tag');

// Désinscrire
sdk.asset.unRegisterOnSelectAsset('mon-tag');

Pathfinding Service

Accessible via sdk.pathfinding

// Itinéraire vers une entité
sdk.pathfinding.setItineraryToEntity('entity-id', '#00FF00');

// Itinéraire vers un asset
sdk.pathfinding.setItineraryToAsset('asset-id', '#FF0000');

// Itinéraire vers plusieurs assets
sdk.pathfinding.setItineraryToAssets(['id1', 'id2'], '#0000FF');

// Par codes de localisation
sdk.pathfinding.setItineraryToAssetsByLocationCode(['CODE1', 'CODE2'], '#FFFF00');

// Itinéraire vers un étage
sdk.pathfinding.setItineraryToFloor('floor-id', '#00FFFF');

// Effacer les itinéraires
sdk.pathfinding.clearItineraries();

Floor Service

Accessible via sdk.floor

// Récupérer les étages disponibles
const floors = await sdk.floor.getFloors();

// Afficher des étages spécifiques
sdk.floor.setFloors(['floor-1', 'floor-2'], true); // true = masquer les autres

// Réinitialiser (afficher tous les étages)
sdk.floor.resetFloors();

Heatmap Service

Accessible via sdk.heatmap

// Afficher une heatmap pour une période
sdk.heatmap.displayHeatmap('2024-01-01', '2024-01-31', 'category');

// Précharger des données
sdk.heatmap.preloadHeatmap('2024-01-01', '2024-01-31', ['cat1', 'cat2']);

// Afficher une heatmap préchargée
sdk.heatmap.displayPrelodedHeatmap('cat1');

// Charger des points personnalisés
sdk.heatmap.loadHeatmapPoint(points, scaleValues);

// Définir l'échelle
sdk.heatmap.setHeatmapScale([0, 25, 50, 75, 100]);

// Masquer/Effacer
sdk.heatmap.hideHeatmap();
sdk.heatmap.clearHeatmap();

User Service

Accessible via sdk.user

// Position de l'utilisateur
const position = await sdk.user.getUserPosition();

// Définir la position
sdk.user.setUserPosition(longitude, latitude, floorIndex);

// Centrer la caméra sur l'utilisateur
sdk.user.moveCameraToUserPosition();

UI Service

Accessible via sdk.ui

sdk.ui.ShowAllUI();
sdk.ui.HideAllUI();

Metadata Service

Accessible via sdk.metadata

// Récupérer tous les groupes de métadonnées
const groups = await sdk.metadata.getAll();

// Par asset
const assetMetadata = await sdk.metadata.getByAssetId('asset-id');

// Créer un groupe
await sdk.metadata.create('asset-id', 'Nom du groupe', { key: 'value' });

// Mettre à jour
await sdk.metadata.update('asset-id', metadataGroup);

// Supprimer
await sdk.metadata.delete('asset-id', 'metadata-group-id');

Système d'événements

Le SDK utilise un système d'événements basé sur des callbacks avec des tags pour la gestion.

Événements disponibles

| Service | Événement | Méthode d'inscription | |---------|-----------|----------------------| | Asset | Sélection | registerOnSelectAsset(callback, tag) | | Asset | Désélection | registerOnUnselectAsset(callback, tag) | | Asset | Survol | registerOnHoverAsset(callback, tag) | | Asset | Fin de survol | registerOnHoverLeaveAsset(callback, tag) |

Exemple complet

// Inscription aux événements
sdk.asset.registerOnSelectAsset((event) => {
    console.log('Asset sélectionné:', event.entityId);
    // Mettre en surbrillance l'asset sélectionné
    sdk.asset.setHighlightAssetById(event.entityId, true);
}, 'selection-handler');

sdk.asset.registerOnUnselectAsset((event) => {
    // Retirer la surbrillance
    sdk.asset.setHighlightAssetById(event.entityId, false);
}, 'selection-handler');

// Nettoyage
function cleanup() {
    sdk.asset.unRegisterOnSelectAsset('selection-handler');
    sdk.asset.unRegisterOnUnselectAsset('selection-handler');
}

Architecture

Structure du projet

SDK-JS/
├── src/
│   ├── sdk.ts                 # Classe principale du SDK
│   ├── unityManager.ts        # Communication avec Unity
│   ├── utils.ts               # Utilitaires
│   ├── services/              # Services du SDK
│   │   ├── baseService.ts
│   │   ├── apiService.ts
│   │   ├── cameraService.ts
│   │   ├── assetService.ts
│   │   ├── pathfindingService.ts
│   │   ├── floorService.ts
│   │   ├── heatmapService.ts
│   │   ├── userService.ts
│   │   ├── uiService.ts
│   │   ├── metadataService.ts
│   │   ├── sceneService.ts
│   │   └── applicationService.ts
│   └── models/
│       ├── apiModels/         # Modèles API
│       └── unityEventModels/  # Modèles d'événements Unity
├── build/                     # Fichiers compilés
├── package.json
├── tsconfig.json
└── rollup.config.ts

Communication

Le SDK utilise trois couches de communication :

1. JavaScript ↔ Unity : Communication bidirectionnelle via SendMessage() et callbacks
2. JavaScript ↔ API REST : Requêtes HTTP pour les données persistantes
3. SignalR : Communication temps réel (optionnel)

Développement

Scripts disponibles

# Build complet
npm run build-app

# Build Rollup uniquement
npm run build-rollup

# Générer la documentation
npm run build-doc

# Build et publication npm
npm run build-and-publish

Build local

# Installation des dépendances
npm install

# Compilation TypeScript + bundling
npm run build-app

Les fichiers compilés sont générés dans le dossier build/ :

• sdk.js : Module compilé
• sdk.d.ts : Définitions TypeScript
• fno-sdk.js : Bundle distribution (IIFE)

Prérequis navigateur

• Support WebGL (pour le rendu Unity 3D)
• Support ES5+ (ou polyfills)
• API Fetch
• Promises

Navigateurs recommandés : Chrome, Firefox, Safari, Edge (versions récentes)

Exports

import Sdk, { MetadataGroup, Asset, signalR } from 'fno-sdk';

Le SDK est également accessible globalement via window.fnoSdk après chargement du bundle.

License

Propriétaire - Find & Order