iOS SDK

heypster SDK lets you embed a GIF picker directly in an iOS app while still giving you the low-level building blocks needed to compose your own interface.

Requirements

• iOS 16.0 or later
• watchOS 9.0 or later
• visionOS 1.0 or later
• macOS 11 or later

Capabilities

HeypsterView

The simplest and recommended route is to present HeypsterView inside a standard system sheet. It provides the day’s GIFs, keyword search, and emotion-based browsing out of the box.

HeypsterView is currently available on iOS and visionOS.

Custom components

The SDK also exposes the UI components and controller logic we use in our own apps, from Apple Watch to Vision Pro.

Use that layer when you need more control over layout, navigation, or the way Heypster content is blended into your existing UI.

Installation (SPM)

Your application needs an API key to authenticate with the heypster service. Request one at contact@heypster.com.

Then add the Swift package from the Heypster repository to your project.

Open the Heypster SDK repository

Demo app

A demo application is included to show the recommended setup end to end. To run it on a device or simulator:

• Download or clone the repository.
• Open `HeypsterSDK.xcworkspace`.
• Set your own signing team if needed.
• Select the Demo target, then build and run on the destination of your choice.

Usage

These snippets cover the minimum setup required to initialize the SDK, present the picker, and display the selected GIF in your interface.

1. Initialization

Initialize the SDK when your app launches by providing your API key and application identifier.

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"))
    }
}

In a UIKit application, call the same initialization from AppDelegate.didFinishLaunching.

2. Presenting HeypsterView

Provide an instance of HeypsterView to a SwiftUI sheet modifier and request its presentation when needed.

HeypsterView returns the selected GIF through a callback. From there, you can read the HeypsterGIF payload, access the temporary file URL stored in transferable, and reuse it in your own flow or system share actions.

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. Displaying a GIF in your UI

Use GIFView with the selection result to render the chosen Heypster GIF directly inside your interface.

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

Android SDK

heypster SDK lets you add a GIF picker to an Android app quickly, while keeping the option to reuse the underlying components in a more custom integration.

Prerequisites

Android 7.0 (API level 24) or later.

Install the AAR module

For security and privacy reasons, the Android SDK is distributed as an AAR module that you integrate directly into your Android project.

Get the module

Add the Gradle dependency

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"))

Initialize the client

The SDK needs an API key to authenticate your application with the heypster service. Contact us to request one, then initialize the client before presenting the picker.

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

Present HeypsterView and GifView

The recommended integration path is to use HeypsterView. It is delivered as a BottomSheetDialogFragment that can be shown from a standard FragmentActivity.

HeypsterView shows the GIFs of the day by default and supports emotion-based discovery and search.

After a user selects a GIF, you can display it with GifView.

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

Declare GifView in XML

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

Web SDK

heypster-gif provides a vanilla JavaScript SDK so you can embed search and selection flows directly in your web application.

Get an API key

The web SDK requires an API key. Request one at contact@heypster.com, then keep it available for initialization and runtime requests.

Install the package

Install the package in your web application with npm:

npm install heypster-gif

Initialize the package

Import the `index.js` entry point from the heypster-gif package.

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

Create an instance of `HeypsterGifSDK`. The constructor accepts the following arguments:

• apiKey: required. The API key assigned to your application.
• initialize: optional. Default value: false.
• language: optional. Default value: fr.
• position: optional. Default value: top. Alternate value: bottom.
• interface: optional. Default value: v1. Alternate values: v2, v3.
• external: available only with the MAX plan. { provider: 'giphy' or 'tenor', key: 'API key for the selected service' }.

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

Keyword and tag searches are always executed in English. The language option adds a secondary interface language and defaults to fr.

The interface version controls the picker layout and capabilities. Version 1 focuses on categories and search, version 2 adds emoji and tag discovery with a refreshed suggestion feed, and version 3 can display external providers such as GIPHY or Tenor alongside the Heypster catalog.

Open the picker

If initialize is set to true, the SDK component is loaded as soon as the page is ready. In that mode, your button only needs to call togglePopup().

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

If initialize is omitted or set to false, the component is not loaded on page startup. Initialize it the first time the user opens the 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();
});

Lazy loading keeps the initial page load lighter, although the first render of the component may take a little longer.

Handle the selected GIF

From the generated interface, users can browse categories or run keyword searches. Results are then displayed inside the picker.

Every click on a GIF triggers the custom heypsterGifClicked event on window. You can listen to it like this:

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

• gifMini: URL of the mini GIF rendition.
• h264: URL of the MP4 rendition encoded in H.264.

For long-term availability, we recommend storing selected GIF assets inside your own infrastructure. Direct asset links can still be used when you want the lightest possible integration.