Interface AppClipHandoffSource

public interface AppClipHandoffSource

Reads the invite code an iOS App Clip left behind for the full application.

This is the iOS half of deterministic attribution, and the counterpart of InstallReferrerSource on Android. An App Clip is launched by the invite link itself and receives that link exactly, so it can write the code into the container it shares with the full application before offering the App Store. When the person installs, the application reads it here: the code made the whole trip through the store, so nothing is matched or guessed.

It replaced a statistical match against a hashed device profile, which existed only because the App Store carries no referrer of its own. Nothing about the visitor is collected any more.

The Codename One build supplies the implementation on platforms that have one and registers it through Invites.registerAppClipHandoffSource(AppClipHandoffSource) before the application starts. Where none is registered -- the simulator, the desktop build, Android, and any iOS application built without an App Clip -- Invites behaves exactly as it does when a clip left nothing.

An application does not implement this interface.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    discardHandoff()
    Told that the framework is done with the handoff, so a source holding the only other copy must discard it.
    boolean
    isSupported()
    Whether this source can answer at all on the current device.
    void
    requestHandoff(AppClipHandoffCallback callback)
    Asks for the code an App Clip left behind.

  • Method Details

    • isSupported

      boolean isSupported()

      Whether this source can answer at all on the current device.

      Returns

      true when a shared container is reachable

    • requestHandoff

      void requestHandoff(AppClipHandoffCallback callback)

      Asks for the code an App Clip left behind. The answer arrives on the callback, possibly asynchronously and possibly on another thread; Invites marshals it back onto the EDT.

      The handoff is read once and cleared by the implementation, so a code cannot be claimed twice by two launches.

      Parameters
      • callback: receives the answer, never null

    • discardHandoff

      boolean discardHandoff()

      Told that the framework is done with the handoff, so a source holding the only other copy must discard it.

      The iOS source hands over a value it reads out of the container it shares with the App Clip, and that container is the ONLY durable copy until the framework writes its own. Emptying it as it read meant a failed write, or a process that exited in between, destroyed the exact code -- and the next launch, finding no handoff, settled an invited install as no_match for ever. So the read leaves the container alone and this is what empties it.

      Two things end the framework's interest, and BOTH have to empty the container, which is why this is one method rather than a "persisted" one:

      • the code reached durable storage, so the copy is redundant. Never called while the write is still failing: the code stays where it is and the next launch reads it again, which is the outcome a retry can still fix.
      • the framework is FORGETTING -- Invites.reset() or an erasure. A handoff that was never consumed is still a code naming an inviter, and the container is read on launch, so one left behind re-attributes the device afterwards and undoes exactly what was erased.

      A source with nothing to discard -- anything that did not hand over its only copy -- answers true here without doing anything.

      Returns

      true when no handoff is left on the device. An erasure is REFUSED on false: the container is read on launch, so a copy that survives is an exact code naming an inviter that the next launch re-attributes from, and reporting an erasure that did not happen is worse than failing one that can be retried.