FyreMemories Android SDK documentation

// In your SplashActivity, MainActivity, or wherever you check auth state
if (FirebaseAuth.getInstance().currentUser != null) {
    FyreMemories.init(
        context = applicationContext,
        config = FyreMemoriesConfig(enableLogging = BuildConfig.DEBUG)
    )
    // proceed to main screen
} else {
    // send user to login screen
}

// After signInWithCredential, signInWithEmailAndPassword, signInAnonymously, or any other provider
firebaseAuth.signIn(...).addOnSuccessListener {
    FyreMemories.init(
        context = applicationContext,
        config = FyreMemoriesConfig(enableLogging = BuildConfig.DEBUG)
    )
    // proceed to main screen
}

// Register once, e.g. in Application.onCreate()
FirebaseAuth.getInstance().addAuthStateListener { auth ->
    if (auth.currentUser != null && !FyreMemories.isInitialized) {
        FyreMemories.init(context = applicationContext)
    }
}

lifecycleScope.launch {
    FyreMemories.awaitInitialized()
    val userId = FyreMemories.currentUserId() ?: return@launch
    val result = FyreMemories.repository.fetchMemories(userId)
}

FyreMemories.init(
    context = this,
    config = FyreMemoriesConfig(
        baseUrl = "",                                  // empty = built-in production URL
        customization = FyreCustomization(/* ... */),  // optional UI overrides
        enableLogging = BuildConfig.DEBUG,
        cacheSizeBytes = 200L * 1024 * 1024,           // video cache (200 MB)
        thumbnailCacheSizeBytes = 50L * 1024 * 1024,   // thumbnail cache (50 MB)
        themeOverlay = R.style.MyFyreOverlay,          // optional theme overlay
        logger = MyTimberLogger(),                     // optional log sink
        connectTimeoutMs = 10_000L,
        readTimeoutMs = 15_000L,
        writeTimeoutMs = 15_000L,
    )
)

val userId: String? = FyreMemories.currentUserId()
// email for authenticated users, uid for anonymous, null if signed out

FyreMemories.setUser(newUserId)

FyreMemories.markAsViewed(memory.id)

FyreMemories.clearUser()
FirebaseAuth.getInstance().signOut()

val userId = FyreMemories.currentUserId() ?: return
val carousel = findViewById<MemoriesCarouselView>(R.id.memoriesCarousel)
carousel.bind(lifecycleOwner = this, userId = userId)

carousel.onMemoryClickListener = OnMemoryClickListener { memory, position ->
    MemoriesFeedActivity.start(this, userId, startPosition = position)
}

FyreMemories.openFeed(context)                        // start at position 0
FyreMemories.openFeed(context, startPosition = 3)    // jump to a memory

MemoriesFeedActivity.start(context, userId, startPosition = 3)
MemoriesFeedActivity.isActive()      // is the feed on screen?
MemoriesFeedActivity.closeCurrent()  // close it programmatically

// Host the fragment inside your own screen
supportFragmentManager.beginTransaction()
    .replace(R.id.container, MemoriesFeedFragment.newInstance(userId, startPosition = 0))
    .commit()

val userId = FyreMemories.currentUserId() ?: return

lifecycleScope.launch {
    FyreMemories.repository.fetchMemories(userId)  // updates state and cache
}

lifecycleScope.launch {
    FyreMemories.repository.memories(userId).collect { result ->
        result
            .onSuccess { memories -> renderList(memories) }
            .onFailure { error -> showError(error) }
    }
}

FeedOptions(
    showLike = true, showSave = true, showDownload = true,
    showShare = true, showClose = true, showSeekBar = true,
    showPositionText = true,       // "3 / 20" counter

    // Custom icons (@DrawableRes; 0 = SDK default)
    iconLikeOutline = R.drawable.ic_heart_outline,
    iconLikeFilled  = R.drawable.ic_heart_filled,
    iconSave = R.drawable.ic_save, iconDownload = R.drawable.ic_download,
    iconShare = R.drawable.ic_share, iconClose = R.drawable.ic_close,
    iconPlay = R.drawable.ic_play,

    // Colors (ARGB; 0 = theme attr)
    likedTint = Color.RED, unlikedTint = Color.WHITE,
    chromeTint = Color.WHITE, backgroundColor = Color.BLACK,

    // Optional message overrides (null = resource string)
    shareChooserTitle = null, downloadFailedText = null,
    storagePermissionDeniedText = null,

    // Playback
    autoAdvanceOnComplete = true, autoAdvanceDelayMs = 300L,
    loopCurrent = false, tapToPlayPause = true,
)

FyreMemories.updateFeedOptions { it.copy(showSave = false, likedTint = Color.RED) }

PlayerOptions(
    autoPlay = true, loop = false, mutedByDefault = false,
    playbackSpeed = 1.0f,                 // must be > 0
    resizeMode = ResizeMode.FIT,          // FIT | FILL | ZOOM
    prefetchNext = true,                  // pre-buffer the next video
    cacheSizeBytes = 200L * 1024 * 1024,  // 200 MB default; must be >= 0
)

FyreMemories.updatePlayerOptions { it.copy(mutedByDefault = true, playbackSpeed = 1.5f) }

CardOptions(
    aspectRatio = AspectRatio.PORTRAIT_9_16,   // LANDSCAPE_16_9 | SQUARE_1_1 | INSTAGRAM_4_5
    thumbnailQuality = ThumbnailQuality.HIGH,  // LOW | MEDIUM | HIGH | ORIGINAL
    cardElevationDp = 0f,
    cardCornerRadiusDp = 12f,
    cardBackgroundColor = 0xFF000000.toInt(),
)

FyreMemories.updateCardOptions { it.copy(cardCornerRadiusDp = 0f) }

LayoutOptions(
    carouselPaddingDp = 8,
    carouselMarginStartDp = 0, carouselMarginEndDp = 0,
    carouselMarginTopDp = 0,  carouselMarginBottomDp = 0,
    headerPaddingStartDp = 12, headerPaddingEndDp = 12,
    headerPaddingTopDp = 12,  headerPaddingBottomDp = 4,
    headerBackgroundColor = Color.TRANSPARENT,
    viewAllPaddingDp = 4, viewAllBackgroundColor = Color.TRANSPARENT,
    thumbnailCornerRadiusDp = 12f,
    showLoadingIndicator = true,
    loadingIndicatorColor = Color.WHITE,
    loadingIndicatorSizeDp = 24f,
    showPlayButton = true,
    playButtonColor = 0xFF6750A4.toInt(),
    playButtonBackgroundColor = Color.TRANSPARENT,
    playButtonSizeDp = 24f,
    feedButtonPaddingDp = 8, feedButtonMarginDp = 12,
)

FyreMemories.updateLayoutOptions { it.copy(thumbnailCornerRadiusDp = 0f) }

TypographyOptions(
    fontFamily = Typeface.createFromAsset(assets, "fonts/MyFont.ttf"),
    headerTitleTypeface = null,      // null = use fontFamily
    headerTitleSizeSp = 18f,
    headerTitleWeight = Typeface.BOLD,
    headerTitleColor = Color.WHITE,
    headerTitleLetterSpacing = 0f,
    headerButtonTypeface = null,
    headerButtonSizeSp = 14f,
    headerButtonWeight = Typeface.NORMAL,
    headerButtonColor = Color.WHITE,
    headerButtonAllCaps = false,
    positionTextSizeSp = 14f,
    positionTextWeight = Typeface.NORMAL,
)

FyreMemories.updateTypographyOptions { it.copy(headerTitleColor = Color.BLACK) }

GradientOptions(
    showGradient = true,
    gradientOpacity = 0.4f,                              // 0.0 - 1.0
    gradientTopColor = 0x00000000,
    gradientBottomColor = 0xFF000000.toInt(),
    gradientDirection = GradientDirection.TOP_TO_BOTTOM, // TOP_TO_BOTTOM | BOTTOM_TO_TOP | LEFT_TO_RIGHT | DIAGONAL
)

FyreMemories.updateGradientOptions { it.copy(gradientOpacity = 0.6f) }

AnimationOptions(
    enableAnimations = true,             // master toggle for all animations
    enableHeartAnimation = true,         // like pop
    enableShimmerAnimation = true,       // loading shimmer
    enableButtonPressAnimation = true,   // button press feedback
    heartAnimationDurationMs = 300L,
    shimmerAnimationDurationMs = 1000L,
    buttonPressAnimationDurationMs = 150L,
)

FyreMemories.updateAnimationOptions { it.copy(enableHeartAnimation = false) }

ProgressOptions(
    seekBarThicknessDp = 4f,
    seekBarScrubberSizeDp = 12f,
    seekBarCornerRadiusDp = 2f,
    loadingIndicatorSizeDp = 24f,
    loadingIndicatorThicknessDp = 3f,
    loadingIndicatorColor = Color.WHITE,
    progressIndicatorStyle = ProgressIndicatorStyle.LINEAR, // LINEAR | CIRCULAR
)

FyreMemories.updateProgressOptions { it.copy(progressIndicatorStyle = ProgressIndicatorStyle.CIRCULAR) }

HapticOptions(
    enableHaptics = true,
    hapticOnLike = true,
    hapticOnActionButtons = true,
    hapticOnNavigation = false,
    hapticOnLongPress = true,
)

FyreMemories.updateHapticOptions { it.copy(enableHaptics = false) }

SoundOptions(
    enableSounds = true,
    soundOnSwipe = false,
    soundOnLike = true,
    soundOnActionSuccess = true,
    likeSoundResId = R.raw.pop,      // @RawRes
    soundVolume = 0.7f,              // 0.0 - 1.0
)

FyreMemories.updateSoundOptions { it.copy(enableSounds = true, soundVolume = 0.5f) }

IconButtonOptions(
    showLikeButton = true,
    likeButtonColor = Color.WHITE, likedButtonColor = Color.RED,
    likeButtonSizeDp = 28f,
    showSaveButton = true, saveButtonColor = Color.WHITE,
    showShareButton = true, shareButtonColor = Color.WHITE,
    showPlayButton = true, playButtonSizeDp = 48f,
    buttonPaddingDp = 8, buttonMarginDp = 12,
)

val heart = ContextCompat.getDrawable(context, R.drawable.ic_heart)
FyreMemories.updateIconButtonOptions {
    it.copy(showSaveButton = false, customLikedIcon = heart, likedButtonColor = Color.RED)
}

AnalyticsOptions(
    enabled = true,
    enabledEvents = emptySet(),  // empty = collect all; or setOf("PLAYED", "LIKED")
    flushIntervalMs = 30_000L,
    flushBatchSize = 20,
    debugOnly = false,           // log events but don't send them
)

FyreMemories.setAnalyticsEnabled(false)  // consent screen helper
FyreMemories.updateAnalyticsOptions { it.copy(debugOnly = true) }

// Compact cards, subtle gradient
val featuredCarousel = MemoriesCarouselView(context).apply {
    bind(this@Activity, userId)
    withLayout(thumbnailCornerRadiusDp = 4f, carouselPaddingDp = 4)
    withGradient(gradientOpacity = 0.2f)
}

// Larger cards, custom title, stronger gradient
val recentCarousel = MemoriesCarouselView(context).apply {
    bind(this@Activity, userId)
    setTitle("Recent Memories")
    setShowViewAll(true)
    withLayout(thumbnailCornerRadiusDp = 16f, carouselPaddingDp = 12)
    withTypography(headerTitleSizeSp = 20f, headerTitleColor = Color.BLACK)
    withGradient(gradientOpacity = 0.7f, gradientDirection = GradientDirection.BOTTOM_TO_TOP)
    withCard(aspectRatio = AspectRatio.PORTRAIT_9_16, cardElevationDp = 4f)
}

carousel
    .withLayout(thumbnailCornerRadiusDp = 8f)
    .withGradient(showGradient = false)
    .withTypography(headerTitleColor = Color.WHITE)
    .withHaptics(enableHaptics = true, hapticOnLike = true)
    .bind(lifecycleOwner, userId)

carousel.setPresentationMode(PresentationMode.CIRCLE)    // default: rings
carousel.setPresentationMode(PresentationMode.STORIES)  // card tiles

carousel.setTitle("Recent Memories")
carousel.setShowViewAll(true)
carousel.setViewAllText("See All")
carousel.setTitleColor(Color.WHITE)
carousel.setHeaderBackground(Color.TRANSPARENT)
carousel.setTitleSize(18f)

carousel.setThumbSize(80)
carousel.setThumbSpacing(8)
carousel.setRingColor(Color.WHITE)
carousel.setShowRing(true)
carousel.setRingWidth(2)
carousel.setCarouselHeight(120)
carousel.setCarouselMargins(start = 16, top = 8, end = 16, bottom = 8)
carousel.setHeaderPaddingStart(12)
carousel.configureCarousel(thumbSizeDp = 80, thumbSpacingDp = 8, ringColor = Color.WHITE, ringWidthDp = 2)

// Called when user taps a memory (before feed opens)
FyreMemories.setOnMemoryClickListener { memory -> }

// Called when a memory starts playing
FyreMemories.setOnMemoryViewListener { memory -> }

FyreMemories.setOnPlaybackCompletedListener { memory, position, durationMs -> }

// Called when feed is opened or closed
FyreMemories.setOnFeedLifecycleListener(object : OnFeedLifecycleListener {
    override fun onFeedOpened() { }
    override fun onFeedClosed() { }
})

// Called when user taps like / save / share / download
FyreMemories.setOnFeedActionClickListener { memory, action -> }

// SDK errors
FyreMemories.setOnFyreErrorListener { error, context -> }

FyreMemories.setMemoryClickInterceptor { memory, proceed ->
    if (userHasPremium) {
        proceed()
    } else {
        showUpgradePrompt()
    }
}

FyreMemories.setShareIntentBuilder { memory, contentUri ->
    Intent(Intent.ACTION_SEND).apply {
        type = "video/mp4"
        putExtra(Intent.EXTRA_STREAM, contentUri)
        putExtra(Intent.EXTRA_TEXT, "Check this out")
        addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)
    }
}

FyreMemories.setDownloadLocationProvider(object : DownloadLocationProvider {
    override fun directory(memory: MemoryItem): File? =
        File(filesDir, "fyre-downloads").apply { mkdirs() }

    override fun fileName(memory: MemoryItem): String? =
        "memory_" + memory.id + ".mp4"

    override fun onDownloadComplete(memory: MemoryItem, file: File) { }
    override fun onDownloadError(memory: MemoryItem, error: Throwable) { }
})

FyreMemories.setAnalyticsDispatcher { events: List<MemoryEvent> ->
    try {
        myAnalytics.upload(events)
        true                 // delivered
    } catch (e: Exception) {
        false                // keep for the next flush
    }
}

// Reset to the SDK default:
FyreMemories.setAnalyticsDispatcher(null)

enum class EventType {
    VIEWED, PLAYED, PAUSED, COMPLETED, REPLAYED,
    LIKED, UNLIKED, SHARED, DOWNLOADED, SAVED_TO_CLOUD, RATED, ERRORED
}

FyreMemories.logEvent(
    videoId = memory.id,
    eventType = EventType.RATED,
    properties = mapOf("stars" to 5, "surface" to "home_carousel")
)

sealed interface MemoryItem {
    val id: String            // stable id for UI and analytics
    val sourceKey: String     // raw backend key (use with saveMemory)
    val thumbnailUrl: String? // CDN thumbnail URL, or null
    val createdAt: Instant?
    val isViewed: Boolean?
}

data class VideoMemory(
    override val id: String,
    override val sourceKey: String,
    override val thumbnailUrl: String?,
    override val createdAt: Instant?,
    override val isViewed: Boolean?,
    val videoUrl: String,        // CDN MP4 URL, ready for ExoPlayer
    val durationMs: Long? = null,
    val isLiked: Boolean? = null,
    val viewCount: Long? = null,
) : MemoryItem

when (memory) {
    is VideoMemory -> player.load(memory.videoUrl)
    else -> { /* future memory types */ }
}

fun FyreError.toUserMessage(): String = when (this) {
    is FyreError.Network      -> "You're offline. Check your connection."
    is FyreError.Transient    -> "Something went wrong. Pull to retry."
    is FyreError.Unauthorized -> "Please sign in again."
    is FyreError.Forbidden    -> "You don't have access to this content."
    is FyreError.NotFound     -> "That memory is no longer available."
    is FyreError.Protocol     -> "We received an unexpected response."
    is FyreError.Unknown      -> "An unexpected error occurred."
}

FyreMemoriesConfig(
    enableLogging = BuildConfig.DEBUG,
    logger = FyreLogger { level, tag, message, throwable ->
        when (level) {
            FyreLogLevel.ERROR -> Timber.tag(tag).e(throwable, message)
            FyreLogLevel.WARN  -> Timber.tag(tag).w(message)
            else               -> Timber.tag(tag).d(message)
        }
    }
)