Hanping Deep Link URL Scheme Examples (Android & iOS)

hanping-deeplink-examples.md

Hanping Deep Link URL Scheme Examples (Android & iOS)

Hanping supports the following custom URL schemes:

hanping://search?text={TEXT}

hanping://word?t={TRADITIONAL_HANZI}&s={SIMPLIFIED_HANZI}&py={TONE_NUMBERED_PINYIN}

hanpingyue://search?text={TEXT}

hanpingyue://word?t={TRADITIONAL_HANZI}&s={SIMPLIFIED_HANZI}&jp={TONE_NUMBERED_JYUTPING}

• TEXT etc must be URL‑encoded UTF‑8
• TEXT may be Hanzi, Pinyin/Jyutping, or English
• Opens the Hanping app directly if installed

For websites or guaranteed fallbacks, prefer https://hanpingchinese.com links instead.

See Hanping docs for more info on supported URL formats.

Android (Kotlin)

Simple open

fun Context.openHanpingWord(
    trad: String,
    simp: String,
    rawPhonetic: String,
) {
    val uri = Uri.Builder()
        .scheme("hanping") // "hanpingyue" for Cantonese app
        .authority("word")
        .appendQueryParameter("t", trad)
        .appendQueryParameter("s", simp)
        // the phonetic is optional
        .appendQueryParameter("py", rawPhonetic) // "jp" for Cantonese app (jyutping)
        .build()

    val intent = Intent(Intent.ACTION_VIEW, uri)

    try {
        startActivity(intent)
    } catch (e: ActivityNotFoundException) {
        // Hanping not installed → Play Store fallback
        val storeIntent = Intent(
            Intent.ACTION_VIEW,
            Uri.parse("https://play.google.com/store/apps/details?id=com.embermitre.hanping.app")
        )
        startActivity(storeIntent)
    }
}

fun openHanpingSearch(
    text: String,
    onFailure: (() -> Unit)?,
) {
    val context = AndroidContextProvider.context

    val uri = Uri.Builder()
        .scheme("hanping") // "hanpingyue" for Cantonese app
        .authority("search")
        .appendQueryParameter("text", text)
        .build()

    val intent = Intent(Intent.ACTION_VIEW, uri).apply {
        addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
    }

    try {
        context.startActivity(intent)
    } catch (e: ActivityNotFoundException) {
        onFailure?.invoke()
    }
}

---

With package check (optional)

fun openHanping(context: Context, text: String) {
    context.openHanpingSearch(text) {
        // Hanping not installed → Play Store
        // Note: for Hanping Cantonese use com.embermitre.hanping.cantodict.app.pro
        val storeUri = Uri.parse("market://details?id=com.embermitre.hanping.app.pro")
        context.startActivity(Intent(Intent.ACTION_VIEW, storeUri))
    }
}

---

iOS (Swift)

Simple open

func openHanpingWord(trad: String, simp: String, rawPhonetic: String) {
    var components = URLComponents()
    components.scheme = "hanping" // "hanpingyue" for Cantonese app
    components.host = "word"
    components.queryItems = [
        URLQueryItem(name: "t", value: trad),
        URLQueryItem(name: "s", value: simp),
        // the phonetic is optional
        URLQueryItem(name: "py", value: rawPhonetic) // "jp" for Cantonese app (jyutping)
    ]

    if let url = components.url {
        openURL(url)
    }
}

func openHanpingSearch(text: String) {
    var components = URLComponents()
    components.scheme = "hanping" // "hanpingyue" for Cantonese app
    components.host = "search"
    components.queryItems = [
        URLQueryItem(name: "text", value: text)
    ]
    
    guard let url = components.url else {
        print("Invalid Hanping search URL")
        return
    }
    
    UIApplication.shared.open(url, options: [:], completionHandler: nil)
}

---

With App Store fallback

func openHanping(text: String) {
    openHanpingSearch(text: text) { success in
        if !success {
            // Hanping not installed → App Store
            // Note: for Hanping Cantonese use id6755623391
            if let storeUrl = URL(string: "https://apps.apple.com/app/id6755623311") {
                UIApplication.shared.open(storeUrl)
            }
        }
    }
}

---

Notes

• Always URL‑encode the text, t, s, py, jp parameters.
• hanping:// and hanpingyue:// links open the app directly and may fail silently if the app is not installed.
• These examples are fire‑and‑forget; no callback is guaranteed.
• For web pages, email, or desktop environments, prefer https://hanpingchinese.com links.