SDK iOS

Le SDK heypster vous permet d’intégrer un sélecteur de GIF directement dans une application iOS, tout en conservant les briques bas niveau nécessaires pour composer votre propre interface.

Prérequis

• iOS 16.0 ou version ultérieure
• watchOS 9.0 ou version ultérieure
• visionOS 1.0 ou version ultérieure
• macOS 11 ou version ultérieure

Fonctionnalités

HeypsterView

La voie la plus simple et la plus recommandée consiste à présenter HeypsterView dans une feuille système standard. Vous obtenez immédiatement les GIF du jour, la recherche par mots-clés et la navigation par émotions.

HeypsterView est actuellement disponible sur iOS et visionOS.

Composants personnalisables

Le SDK expose aussi les composants d’interface et la logique de contrôle utilisés dans nos propres applications, de l’Apple Watch au Vision Pro.

Utilisez cette couche lorsque vous avez besoin d’un contrôle plus fin sur la mise en page, la navigation ou la manière dont le contenu Heypster s’intègre à votre UI existante.

Installation (SPM)

Votre application a besoin d’une clé API pour s’authentifier auprès du service heypster. Demandez-la à contact@heypster.com.

Ajoutez ensuite le package Swift depuis le dépôt Heypster dans votre projet.

Voir le dépôt Heypster SDK

Application de démonstration

Une application démo est fournie pour montrer l’intégration recommandée de bout en bout. Pour l’exécuter sur un appareil ou un simulateur :

• Téléchargez ou clonez le dépôt.
• Ouvrez `HeypsterSDK.xcworkspace`.
• Configurez votre équipe de signature si nécessaire.
• Sélectionnez la cible Demo, puis compilez et lancez sur la destination de votre choix.

Utilisation

Les extraits ci-dessous couvrent le minimum nécessaire pour initialiser le SDK, présenter le picker et afficher le GIF sélectionné dans votre interface.

1. Initialisation

Initialisez le SDK au lancement de l’application en fournissant votre clé API et votre identifiant applicatif.

import SwiftUI
import HeypsterSDK

@main
struct DemoApp: App {
    var body: some Scene {
        WindowGroup {
            DemoView()
        }
    }

    init() {
        HeypsterClient.initialize(configuration: .init(secret: "YOUR_APP_SECRET", id: "YOUR_APP_ID"))
    }
}

Dans une application UIKit, appelez la même initialisation depuis AppDelegate.didFinishLaunching.

2. Présenter HeypsterView

Fournissez une instance de HeypsterView à un modificateur de feuille SwiftUI et déclenchez sa présentation au moment voulu.

HeypsterView renvoie le GIF sélectionné via un callback. Vous pouvez alors exploiter l’objet HeypsterGIF, récupérer l’URL temporaire stockée dans transferable et la réutiliser dans votre propre flux ou dans les mécanismes de partage du système.

import SwiftUI
import HeypsterSDK

struct DemoView: View {

    @State private var showGifs = false

    var body: some View {
        Button {
            showGifs = true
        } label: {
            Text("Show HeypsterView")
        }
        .sheet(isPresented: $showGifs) {
            HeypsterView { gif in
            }
        }
    }

}

3. Afficher un GIF dans votre interface

Utilisez GIFView avec le résultat de la sélection pour afficher le GIF Heypster choisi directement dans votre interface.

// Use GIFView to easily present a GIF within your UI.
GIFView(gif: result.gif)
    .id(result)

SDK Android

Le SDK heypster permet d’ajouter rapidement un sélecteur de GIF dans une application Android, tout en laissant la possibilité de réutiliser les composants sous-jacents dans une intégration plus personnalisée.

Prérequis

Android 7.0 (API level 24) ou version ultérieure.

Installer le module AAR

Pour des raisons de sécurité et de confidentialité, le SDK Android est distribué sous la forme d’un module AAR à intégrer directement dans votre projet.

Récupérer le module

Ajouter la dépendance Gradle

implementation("com.google.android.material:material:1.12.0")
implementation("com.google.code.gson:gson:2.10.1")
implementation(files("libs/HeypsterSDK_1.0.0.aar"))

Initialiser le client

Le SDK a besoin d’une clé API pour authentifier votre application auprès du service heypster. Contactez-nous pour l’obtenir, puis initialisez le client avant d’afficher le picker.

HeypsterClient.initialize("** YOUR API KEY **")

Présenter HeypsterView et GifView

Le parcours recommandé consiste à utiliser HeypsterView. Il est fourni sous la forme d’un BottomSheetDialogFragment affichable depuis un FragmentActivity standard.

HeypsterView affiche par défaut les GIF du jour et prend en charge la découverte par émotions ainsi que la recherche.

Après la sélection d’un GIF, vous pouvez l’afficher avec GifView.

val gifView = findViewById<GifView>(R.id.gifView)
val button = findViewById<Button>(R.id.button)
button.setOnClickListener{
    HeypsterView {
        gifView.loadGif(it) }.show(supportFragmentManager)
    }
}

Déclarer GifView en XML

<com.heypster.sdk.views.GifView
android:id="@+id/gifView"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:layout_marginHorizontal="32dp" />

SDK Web

heypster-gif propose un SDK JavaScript vanilla pour intégrer directement les parcours de recherche et de sélection dans votre application web.

Obtenir une clé API

Le SDK Web nécessite une clé API. Demandez-la à contact@heypster.com, puis conservez-la pour l’initialisation et les requêtes d’exécution.

Installer le package

Installez le package dans votre application web avec npm :

npm install heypster-gif

Initialiser le package

Importez le point d’entrée `index.js` du package heypster-gif.

import HeypsterGifSDK from './node_modules/heypster-gif/index.js';

Créez ensuite une instance de `HeypsterGifSDK`. Le constructeur accepte les arguments suivants :

• apiKey : obligatoire. La clé API attribuée à votre application.
• initialize : facultatif. Valeur par défaut : false.
• language : facultatif. Valeur par défaut : fr.
• position : facultatif. Valeur par défaut : top. Valeur alternative : bottom.
• interface : facultatif. Valeur par défaut : v1. Valeurs alternatives : v2, v3.
• external : disponible uniquement avec l’offre MAX. { provider: 'giphy' ou 'tenor', key: 'clé API du service sélectionné' }.

let heypsterSDK = new HeypsterGifSDK('APIkey', true, 'fr', 'top', 'v1', { provider: null, key: null })

Les recherches par mots-clés et par tags sont toujours exécutées en anglais. L’option language ajoute une langue secondaire pour l’interface et vaut fr par défaut.

La version d’interface détermine la présentation du picker et ses capacités. La version 1 se concentre sur les catégories et la recherche, la version 2 ajoute la découverte par emoji et par tags avec un flux de suggestions enrichi, et la version 3 peut afficher des résultats externes comme GIPHY ou Tenor aux côtés du catalogue Heypster.

Ouvrir le picker

Si initialize vaut true, le composant du SDK est chargé dès que la page est prête. Dans ce mode, votre bouton n’a plus qu’à appeler togglePopup().

let heypsterSDK = new HeypsterGifSDK('APIkey', true, 'fr', 'top', 'v1');
document.querySelector('#gif_button').addEventListener('click', e => {
    heypsterSDK.togglePopup();
});

Si initialize est absent ou vaut false, le composant n’est pas chargé au démarrage de la page. Initialisez-le lors de la première ouverture du picker.

let heypsterSDK = new HeypsterGifSDK('APIkey', false, 'fr', 'top', 'v1');
document.querySelector('#gif_button').addEventListener('click', e => {
    if(!heypsterSDK.popupElement){
        heypsterSDK = heypsterSDK.initialize();
    }
    heypsterSDK.togglePopup();
});

Le chargement différé allège le temps de chargement initial de la page, même si le premier rendu du composant peut demander un peu plus de temps.

Récupérer le GIF sélectionné

Depuis l’interface générée, l’utilisateur peut parcourir les catégories ou lancer une recherche par mots-clés. Les résultats sont ensuite affichés dans le picker.

Chaque clic sur un GIF déclenche l’événement personnalisé heypsterGifClicked sur window. Vous pouvez l’écouter ainsi :

window.addEventListener('heypsterGifClicked', (event) => {
    // Access GIF information
    const { gifMini, h264 } = event.detail;
});

• gifMini : URL de la version mini du GIF.
• h264 : URL de la version MP4 encodée en H.264.

Pour garantir la disponibilité dans le temps, nous recommandons de stocker les assets sélectionnés dans votre propre infrastructure. Les liens directs restent possibles si vous cherchez l’intégration la plus légère.