Comment intégrer l’API iCloud Calendar dans votre application

Dans un article précédent, nous avons expliqué comment intégrer l’API Google Calendar à votre application et détaillé toutes les étapes nécessaires pour que l’intégration fonctionne.

L’intégration d’iCloud Calendar n’est pas aussi simple que celle de Google Calendar. La documentation est mince, et Apple n’explique pas vraiment ce que les développeurs doivent faire pour connecter iCloud Calendar à une application.

Dans cet article, nous examinons en détail comment intégrer l’API iCloud Calendar à votre application. Nous abordons l’authentification, les opérations prises en charge, les limitations, des extraits de code et les outils qui facilitent l’intégration.

Quels protocoles et standards le calendrier Apple iCloud utilise-t-il ?

Apple iCloud Calendar s’appuie sur le standard CalDAV pour la communication calendrier. CalDAV est une extension de WebDAV qui permet aux clients de gérer des calendriers et des événements sur un serveur.

Les événements sont représentés au format ICS (iCalendar), un format texte pour les données calendaires. Votre application peut donc communiquer avec les calendriers iCloud via HTTP en utilisant des requêtes CalDAV et des données ICS.

L’avantage est qu’il ne s’agit pas d’une implémentation spécifique à un appareil ou à un système Apple ; vous pouvez l’utiliser depuis n’importe quel serveur, quel que soit le système d’exploitation.

La mauvaise nouvelle, c’est qu’iCloud ne fournit pas d’API REST pour les calendriers : CalDAV est donc la seule façon d’intégrer iCloud Calendar à votre application.

Comment s’authentifier auprès d’iCloud ?

Habituellement, pour intégrer une plateforme dans votre application (par exemple Google Calendar), vous devez créer un compte développeur sur cette plateforme, créer une application, configurer les portées, ajouter des utilisateurs de test, renseigner les informations de votre application et la soumettre pour approbation.

Après avoir suivi toutes ces étapes et obtenu l’approbation, vous pouvez rediriger l’utilisateur final vers l’écran OAuth de la plateforme, où il doit être connecté et accorder explicitement l’accès aux portées demandées par votre application. L’utilisateur final voit aussi le nom de votre application et toutes les informations que vous avez fournies lors de sa configuration sur cette plateforme.

Apple iCloud ne fonctionne pas ainsi. Il n’existe pas de flux OAuth standard comme pour Google Calendar ou Outlook. Pour connecter le calendrier iCloud d’un utilisateur, vous l’authentifiez avec son Apple ID via Basic Auth sur SSL. Comme la plupart des comptes iCloud ont activé l’authentification à deux facteurs, l’utilisateur doit créer un mot de passe spécifique à l’app dans les réglages de son compte Apple ID, au lieu d’utiliser son mot de passe principal.

Votre application demandera donc l’adresse iCloud/Apple ID de l’utilisateur et ce mot de passe spécifique à l’app (16 caractères). Avec ces identifiants, vous pourrez vous connecter au service CalDAV d’iCloud.

Outre les raisons évoquées ci-dessus, Apple impose ces mots de passe spécifiques pour renforcer la sécurité ; partager son mot de passe iCloud avec une application tierce n’est clairement pas recommandé.

Sous le capot, l’en-tête de votre requête HTTP inclura un mot de passe encodé en Base64 : Authorization: Basic <app-specific-password-here>

Quelles méthodes l’API iCloud Calendar prend-elle en charge ?

Le service CalDAV d’iCloud est hébergé sur caldav.icloud.com. Après authentification, les méthodes suivantes sont disponibles :

• Liste des calendriers de l’utilisateur
• CRUD sur les événements
• Récupération d’événements spécifiques

Pour en savoir plus sur CalDAV, consultez la RFC 4791, qui décrit toutes les méthodes et filtres disponibles.

Voici les informations essentielles pour votre intégration iCloud Calendar :

Verbes HTTP pris en charge

Propriétés d’une collection de calendriers

Quelles bibliothèques peuvent simplifier l’intégration ?

Manipuler CalDAV, ICS, XML et les spécificités d’iCloud est fastidieux. Il faut comprendre chaque méthode, convertir le XML en JSON et intégrer le tout dans votre code.

Pour une intégration plus fluide, nous recommandons :

• tsdav : indispensable en JavaScript/TypeScript. Fournit une API TS de haut niveau qui encapsule les verbes HTTP et le XML (PROPFIND, REPORT, MKCALENDAR, PUT, DELETE, …). Voir la documentation tsdav .
• ical-generator : iCloud impose de téléverser des fichiers .ics complets lors de la création ou de la mise à jour d’événements. Cette bibliothèque génère correctement les fichiers (UID, DTSTART/DTEND, RRULE, time-zones, etc.).
• ical.js : moteur JavaScript pur (Mozilla) pour analyser les réponses ICS et les convertir en classes JS.

Tableau récapitulatif du rôle de tsdav :

Exemple d’intégration iCloud Calendar avec tsdav + TypeScript

Dans cet exemple, on suppose que vous avez déjà obtenu l’e-mail de l’utilisateur et son mot de passe spécifique à l’app.

createClient : création du client DAV

import { DAVCalendar, DAVClient, DAVNamespaceShort, DAVObject } from "tsdav";

const APPLE_DAV_URL = "https://caldav.icloud.com";

function createClient({
  username,
  password,
}: {
  username: string;
  password: string;
}) {
  const client = new DAVClient({
    serverUrl: APPLE_DAV_URL,
    credentials: {
      username,
      password,
    },
    authMethod: "Basic",
    defaultAccountType: "caldav",
  });

  return client;
}

constants : fichier de constantes

/*
The prodId value is a required field that must appear on every calendar object.
The field is a globally-unique identifier for the software that 
produced the file. tsdav might automatically generate that information for you,
but it might be best if you provide it manually.

You might find it useful when you have edge cases, you can use it to tell which
program wrote the data.

*/

export const PROD_ID = {
  company: "your-company-name-here",
  product: "your-product-name-here",
};

getCalendars : récupérer tous les calendriers

  async getCalendars(
    ...params: Parameters<typeof DAVClient.prototype.fetchCalendars>
  ): Promise<DAVCalendar[]> {
  
  // You can abstract this initialization into another method.
  // For the sake of simplicity, we'll initialize the client on each method.
   const client = createClient({
    username: <email-here>,
    password: <password-here>,
  });
  
    return client.fetchCalendars(...params);
  }

getCalendarById : récupérer un calendrier par ID

  async getCalendarById(calendarUrl: string): Promise<DAVCalendar> {
    const calendars = await getCalendars();
    const calendar = calendars.find((el) => el.url === calendarUrl);
    if (!calendar) {
      throw new Error(`Apple Calendar with id ${calendarUrl} not found`);
    }

    return calendar;
  }

getCalendarEvents : lister les événements

  async getCalendarEvents(
    calendarUrl: string,
    query: GetCalendarEventsQuery = {}
  ) {
    const client = createClient({
      username: <email-here>,
      password: <password-here>,
    });

    const calendar = await getCalendarById(calendarUrl);

    const events = await client.fetchCalendarObjects({
        calendar,
        timeRange: query.dateRange ?? undefined,
      })

    return { events, nextSyncToken: calendar.syncToken };
  }

getEventById : récupérer un événement par ID

  async getEventById(calendarUrl: string, eventId: string) {
    const client = createClient({
      username: <email-here>,
      password: <password-here>,
    });
    
    const eventUrl = new URL(`${eventId}.ics`, calendarUrl).pathname;

    const responses = await client.calendarMultiGet({
        url: calendarUrl,
        props: {
          [`${DAVNamespaceShort.DAV}:getetag`]: {},
          [`${DAVNamespaceShort.CALDAV}:calendar-data`]: {},
        },
        objectUrls: [eventUrl],
        depth: "1",
      })
    

    if (responses.length === 0) {
      throw new Error(
        `Received no response while fetching ${eventUrl}`,
        null
      );
    } else if (responses[0].status >= 400) {
      throw new Error(
        `Failed to get Apple event by id. Status: ${responses[0].statusText}`,
        responses[0]
      );
    }

    const response = responses[0];
    const calendarObject: DAVObject = {
      url: new URL(response.href ?? "", calendarUrl).href,
      etag: `${response.props?.getetag}`,
      data:
        response.props?.calendarData?._cdata ?? response.props?.calendarData,
    };

    try {
      return calendarObject;
    } catch (err: any) {
      this.logger.error("Failed to process Apple Response", {
        message: err.message,
        event: calendarObject,
      });
      return [];
    }
  }

createEvent : créer un événement

  async createEvent(calendarUrl: string, data: AppleEvent) {
    const client = createClient({
      username: <email-here>,
      password: <password-here>,
    });

    const eventId = data.id ?? <generate-id-here>

    const calendar = ical({
	    prodId: PROD_ID,
      method: ICalCalendarMethod.REQUEST,
    });
    
    const event = calendar.createEvent({ ...data, id: eventId });

    const response = await  client.createCalendarObject({
        calendar: {
          url: calendarUrl,
        },
        filename: `${event.id()}.ics`,
        iCalString: calendar.toString(),
      })
      
    if (!response.ok) {
      throw new Error(
        `Failed to create Apple event: ${response.statusText}`,
        response
      );
    }
    
    return { id: event.id(), eventWithExceptions };
  }

updateEvent : mettre à jour un événement

  async updateEvent(calendarUrl: string, eventId: string, data: AppleEvent) {
    const client = createClient({
      username: <email-here>,
      password: <password-here>,
    });

		
    const originalEventData = await getEventById(calendarUrl, eventId);

    const calendar = ical({
      prodId: PROD_ID,
      method: ICalCalendarMethod.REQUEST,
    });

    for (let event of originalEventData) {
      if (event.status === ICalEventStatus.CANCELLED) continue;

      if (event.id === eventId) {
        calendar.createEvent({ ...event, ...data, id: eventId, url: null });
      } else {
        calendar.createEvent({ ...event, id: eventId, url: null });
      }
    }

    const calendarObjectUrl = new URL(`${eventId}.ics`, calendarUrl);

    const response = await
      client.updateCalendarObject({
        calendarObject: {
          url: calendarObjectUrl.href,
          data: calendar.toString(),
        },
      })

    if (!response.ok) {
      throw new Error(
        `Failed to update Apple event: ${response.statusText}`,
        response
      );
    }

    return getEventById(calendarUrl, eventId);
  }

deleteEvent : supprimer un événement

  async deleteEvent(calendarUrl: string, eventId: string) {
    const client = createClient({
      username: <email-here>,
      password: <password-here>,
    });
    

    const calendarObjectUrl = new URL(`${eventId}.ics`, calendarUrl);

    const response = await client.deleteCalendarObject({
        calendarObject: {
          url: calendarObjectUrl.href,
        },
      })

    if (!response.ok) {
      throw new Error(
        `Failed to delete Apple event: ${response.statusText}`,
        response
      );
    }

    return { id: eventId };
  }

Quelles limites présente iCloud Calendar ?

1. Pas d’API REST ni de réponses JSON : Pour communiquer avec l’API iCloud Calendar, vous devez utiliser CalDAV et manipuler des fichiers .ics. Ce n’est pas idéal, car l’API Outlook Calendar et l’API Google Calendar proposent des API REST qui fonctionnent en JSON et sont bien plus productives. Vous pouvez utiliser les bibliothèques suggérées ci-dessus pour faciliter la communication avec l’API iCloud Calendar, mais cela dépendra au final du langage et du framework que vous utilisez, car tous les frameworks ne disposent pas de bibliothèques qui facilitent cette communication.
2. Documentation lacunaire : Bien que nous ayons renvoyé vers la documentation officielle de CalDAV, sachez que toutes les méthodes ne fonctionnent pas avec l’API iCloud Calendar. Préparez-vous à des pièges et à beaucoup de tests.
3. Basic Auth avec mot de passe spécifique à l’app : Comme indiqué, iCloud ne suit pas les conventions standard d’OAuth 2.0. Vous devez utiliser un mot de passe spécifique à l’app pour vous authentifier et communiquer avec iCloud Calendar.
4. Pas de webhooks ni de notifications push : Contrairement à Google Calendar ou Outlook, iCloud n’offre pas la meilleure API de calendrier , car vous ne pouvez pas enregistrer de webhooks pour être notifié des changements dans les calendriers. Les applications tierces ne peuvent pas s’abonner aux mises à jour en direct. Une solution de contournement consiste à interroger le serveur périodiquement et à utiliser le rapport sync-collection pour récupérer efficacement les changements.
5. Pas de méthode PATCH : Vous ne pouvez pas utiliser PATCH pour mettre à jour partiellement un événement ; vous devez faire un PUT complet.
6. Aucun contrôle sur les invitations : iCloud Calendar gère automatiquement les invitations aux réunions. Si vous créez ou modifiez un événement avec des participants, iCloud Calendar envoie les invitations et met à jour le statut des participants. Vous ne pouvez pas utiliser l’Outbox/Inbox de planification CalDAV pour contrôler manuellement les invitations.

Existe-t-il une solution plus simple pour intégrer iCloud Calendar ?

Intégrer iCloud Calendar n’est pas une mince affaire. iCloud ne suit pas les conventions habituelles des calendriers, et de nombreuses méthodes et filtres CalDAV censés fonctionner ne fonctionnent tout simplement pas.

Une approche plus simple consiste à utiliser une API de calendrier unifiée.

Utiliser une API de calendrier unifiée comme Apiroc présente les avantages suivants :

• Intégrez iCloud Calendar dans votre application via une API bien documentée et testée, conforme aux standards modernes. Avec Apiroc, un compte iCloud se connecte avec l’e-mail de l’Apple ID et un mot de passe spécifique à l’app en un seul appel API, et les événements sont renvoyés en JSON plutôt qu’en ICS.
• Passez moins de temps à développer et à maintenir l’intégration. L’essentiel du travail est déjà fait : l’API, le client et les cas particuliers. Vous n’avez pas non plus à maintenir l’intégration ni à corriger les nouveaux cas particuliers qui apparaissent au fil du temps.
• Intégrez d’autres fournisseurs de calendrier en plus d’iCloud Calendar, sans effort supplémentaire. Apiroc prend en charge Google Calendar et Microsoft Outlook via la même API, ce qui rend l’ajout de nouveaux fournisseurs à votre application très simple.
• Webhooks pour Google Calendar et Outlook, prise en charge d’iCloud prévue. Apiroc envoie dès aujourd’hui des notifications en temps réel pour les calendriers Google et Microsoft. Les webhooks pour les calendriers iCloud sont prévus. En attendant, vous devez encore interroger iCloud pour détecter les changements, ce qu’Apiroc simplifie grâce aux jetons de synchronisation.

Utilisez Apiroc pour intégrer iCloud Calendar à votre application

Vous n’avez pas à gérer vous-même toutes les complexités liées à l’intégration d’iCloud Calendar dans votre application. Utilisez plutôt Apiroc, une API de calendrier unifiée conçue par une équipe qui a des années d’expérience en intégrations de calendriers. Le plan gratuit inclut jusqu’à 10 End User Accounts et un nombre illimité de requêtes API. Vous pouvez vous inscrire gratuitement, aucune carte de crédit requise.

FAQ

Quel protocole iCloud Calendar utilise-t-il ?

Il utilise CalDAV via HTTP et stocke les événements au format iCalendar (ICS).

iCloud Calendar propose-t-il une API REST ?

Non. CalDAV est le seul moyen de lire et d’écrire des données iCloud Calendar.

Comment s’authentifie-t-on auprès d’iCloud Calendar ?

On transmet l’identifiant Apple de l’utilisateur (souvent l’e-mail) et un mot de passe spécifique d’application de 16 caractères via Basic Auth sur SSL.

iCloud Calendar prend-il en charge les notifications push ou les webhooks ?

Non. Il faut interroger le serveur pour détecter les changements.

Quelles bibliothèques simplifient l’intégration ?

tsdav (client CalDAV), ical-generator (génération d’ICS) et ical.js (analyse d’ICS) gèrent la plupart des détails bas niveau.

Comment éviter de manipuler CalDAV et ICS directement ?

Utilisez une API de calendrier unifiée comme Apiroc, qui réunit iCloud, Google et Outlook dans une seule interface JSON moderne.