{"id":13343666,"url":"https://github.com/xkawi/micro-link","last_synced_at":"2025-04-07T15:32:49.611Z","repository":{"id":44750349,"uuid":"73037447","full_name":"xkawi/micro-link","owner":"xkawi","description":"a minimalistic microservice to generate and resolve sharable dynamic link  (a.k.a deeplink)","archived":false,"fork":false,"pushed_at":"2022-01-27T01:19:51.000Z","size":9,"stargazers_count":11,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-22T20:26:26.348Z","etag":null,"topics":["deeplink","micro","microservice","nodejs","now","zeit"],"latest_commit_sha":null,"homepage":"https://micro-link.now.sh","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xkawi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-11-07T03:03:27.000Z","updated_at":"2023-06-19T08:16:25.000Z","dependencies_parsed_at":"2022-09-06T09:40:45.139Z","dependency_job_id":null,"html_url":"https://github.com/xkawi/micro-link","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xkawi%2Fmicro-link","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xkawi%2Fmicro-link/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xkawi%2Fmicro-link/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xkawi%2Fmicro-link/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xkawi","download_url":"https://codeload.github.com/xkawi/micro-link/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247679886,"owners_count":20978153,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deeplink","micro","microservice","nodejs","now","zeit"],"created_at":"2024-07-29T19:31:56.717Z","updated_at":"2025-04-07T15:32:45.088Z","avatar_url":"https://github.com/xkawi.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"### Introduction\n\n`micro-link` is a minimalistic microservice that lets you easily generate and resolve sharable dynamic link (a.k.a deeplink). no database. no fancy architecture. just a microservice powered by [micro](https://github.com/zeit/micro).\n\n### Generating a Dynamic Link\n\nSimply send a POST request to `https://micro-link.now.sh` in this way:\n\n```\nPOST https://micro-link.now.sh\n\nRequest Body:\n{\n  web: \"https://google.com\" (required),\n  ios: \"google://search\" (optional),\n  android: \"google://search\" (optional)\n}\n```\n\nplease take note that, the \"web\" link is required because that will always be the fallback link. You can try using tools like [Postman](https://www.getpostman.com/) or `curl` to make the network request:\n\n`echo '{\"web\":\"google.com\"}' | curl -d @- https://micro-link.now.sh`\n\nThe response contains a JSON object with the generated dynamic link like this:\n\n```\n{\n  link: \"https://micro-link.now.sh?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3ZWIiOiJodHRwczovL3FhbnZhc3QuY29tIiwiaW9zIjoicWFudmFzdDovL2Rpc2NvdmVyeSIsImlhdCI6MTQ3ODUzMDE3NX0.eQao9zz3sskQTxaOUETQlB-QeYUmHVEqkF8905id-6M\"\n}\n``` \n\n`micro-link` simply acts as an API for you to generate dynamic links. How you are going to utilize the generated dynamic link is totally up to your needs.\n\n### Resolving a Dynamic Link\n\nSimply make a GET request to the generated dynamic link to resolve it:\n\n```\nGET https://micro-link-jzbxhzqoqd.now.sh?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3ZWIiOiJodHRwczovL3FhbnZhc3QuY29tIiwiaW9zIjoicWFudmFzdDovL2Rpc2NvdmVyeSIsImlhdCI6MTQ3ODUzMDE3NX0.eQao9zz3sskQTxaOUETQlB-QeYUmHVEqkF8905id-6M\n```\n\nDepending on the browser that you use to resolve the link, `micro-link` will automatically detect the browser's User Agent and redirect to the application or website properly.\n\nGive it a try! Generate a simple dynamic link that resolve to any apps of even your own apps, and open the generated link from your iPhone and Android devices to see it in action.\n\n### Under the Hood\n\n`micro-link` utilizes [JSON Web Token](https://github.com/auth0/node-jsonwebtoken) to generate a unique dynamic link for the payload (request body) received. That means you have to supply a secret to JWT to generate the unique token. This token is then included in the response object that contains the \"generated\" dynamic link.\nThis allows `micro-link` to retrieve this token when resolving the dynamic link, and retrieve the payload back for redirection. The redirection is achieved through the use of [useragent](https://github.com/3rd-Eden/useragent) library that detect the client's user agent and pick the correct redirection link from the payload.\n\n### Advance\n\nYou can easily deploy `micro-link` as your own dynamic link microservice as well using [Now](https://zeit.co/now) by [Zeit.co](https://twitter.com/zeithq). Follow this steps:\n\n1. `$ git clone https://github.com/xkawi/micro-link.git`\n2. `$ cd micro-link`\n3. modify the `jwtSecret` and optionally `tokenQueryKey` found at `lib/core.js`\n4. `$ npm install -g now` (ensure that you are using node v6 and above)\n5. `$ now` (you may need to login if it is your first time)\n6. open the copied link in the browser and there you have it! your own dynamic link microservice deployed in less than a minute!\n\nOr just click the icon below to deploy your own microservice to Now:\n\n[![Deploy to now](https://deploy.now.sh/static/button.svg)](https://deploy.now.sh/?repo=https://github.com/xkawi/micro-link\u0026env=JWT_SECRET)\n\n#### Managing Secrets \u0026 Environment Variables\n\nIf you look at `lib/core.js`, there are a few environment variables that you can utilize, they are namely:\n\n1. `JWT_SECRET` - to store your JWT secret securely\n2. `HOST_URL` - used when generating the dynamic link. It is important that this `HOST_URL` can resolve properly, otherwise the dynamic link will not work. By default it uses the deployed url from Now, NOW_URL, which is automatically provided.\n3. `TOKEN_QUERY_KEY` - if you want to customize the query key such as `\u003cHOST_URL\u003e?customKey=\u003cJWT_token\u003e`, you can use this env var to overwrite the default `\u003cHOST_URL\u003e?token=\u003cJWT_token\u003e` key  \n\nRefer to Now's [documentation](https://zeit.co/blog/environment-variables-secrets) in handling secrets and environment variables.\n\n### Roadmap\n\n- show a landing page if the dynamic link cannot be resolved properly on mobile\n- handle Android deeplink the \"correct\" way (as I am not familiar with this)\n- shorten the token? open to any discussion if you have some ideas.\n\n### Contributing\n\nIf you would like to contribute to any of the roadmap above or simply want to contribute discussions or anything, go to `micro-link` github repo [here](https://github.com/xkawi/micro-link) and fork it, open issues, and of course, don't forget to star it!\n\nHave fun!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxkawi%2Fmicro-link","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxkawi%2Fmicro-link","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxkawi%2Fmicro-link/lists"}