docs(firestore-geo-functions): updated documentation and icon (#5)

* docs(firestore-geo-functions): updated documentation and icon * Update PREINSTALL.md * Update extension.yaml to include tags --------- Co-authored-by: huangjeff5 <64040981+huangjeff5@users.noreply.github.com>
googlemaps · May 8, 2023 · 0e71b56 · 0e71b56
1 parent c0ebecc
commit 0e71b56
Show file tree

Hide file tree

Showing 3 changed files with 43 additions and 29 deletions.
diff --git a/firestore-geo-functions/PREINSTALL.md b/firestore-geo-functions/PREINSTALL.md
@@ -1,45 +1,56 @@
-Use this extension to automatically update the latitude and longitude of an address, as well as the best driving time between two addresses, using the Google Maps API. 
+## How This Extension Works
 
-It listens to specified fields in documents within a Firestore collection and updates the `latitude`, `longitude`, and `best driving time` as needed.
+Use this extension to perform geocoding operations on Firestore documents using the Geocoding API and travel time estimates using the Distance Matrix API. This extension can help you:
 
-### Features
+* Automatically deduce the latitude and longitude of an address
+* Figure out the best driving time between two addresses
 
-### Automatically retrieves latitude and longitude for an address.
-This feature listens to Firestore document creation/updates and updates geolocation information accordingly when a valid `address` has been added/updated in a document.
+The extension listens to specified fields in documents within a Firestore collection and updates the latitude, longitude, and best driving time fields as needed.
 
-To ensure best practices, if a document has been updated within the last 30 days, the extension will not update the geolocation information.
+On install, you will be asked to provide a Firestore collection. When documents are created or updated within that collection, a Cloud Function will trigger that calls Geocoding API to execute a geocoding operation.
 
-```js
+### Automatically retrieves latitude and longitude for an address
+
+This feature will geocode an address when a valid address has been added/updated in a document.
+
+```javascript
 admin.firestore().collection('address_book').add({
   address: '1600 Amphitheatre Parkway, Mountain View, CA',
-})
+});
 ```
 
-### Calculates the best driving time between two addresses.
-To calculate the best driving time between two destinations, the extension feature to Firestore document creation/updates and updates `bestDrivingTime` information based on the provided `origin` and `destination` addresses.
+### If an origin and destination are provided to the collection, the extension calls the Distance Matrix API to calculate the best driving time between two addresses
 
-```js
+This extension will calculate bestDrivingTime information based on the provided origin and destination addresses.
+
+```javascript
 admin.firestore().collection('address_book').add({
   origin: '1600 Amphitheatre Parkway, Mountain View, CA',
   destination: '85 10th Ave, New York, NY' 
-})
+});
 ```
 
-### Supports exponential backoff for error handling.
-The extension uses exponential backoff guidelines through Cloud Tasks to ensure that it will continue trying to update the document data for any task. Learn more about this feature.
+### Implements Google Maps Platform Best Practices
+
+According to Google Maps Platform [Terms of Service](https://cloud.google.com/maps-platform/terms/maps-service-terms), geocode information cannot be stored for longer than 30 days. Whenever geocode information is retrieved for a Firestore document, a scheduled Cloud Task is created which will re-query the geocode information after 30 days.
+
+Whenever there are intermittent issues with the Google Maps Platform APIs, this extension implements automatic retries using an exponential backoff strategy as recommended [here](https://developers.google.com/maps/documentation/routes/web-service-best-practices#exponential-backoff).
+
+## Additional setup
+
+Before installing this extension, make sure that you've set up a [Cloud Firestore database](https://firebase.google.com/docs/firestore/quickstart) in your Firebase project. 
+
+Additionally, make sure that you've enabled the [Geocoding API](https://developers.google.com/maps/documentation/geocoding/cloud-setup) and [Distance Matrix API](https://developers.google.com/maps/documentation/distance-matrix/cloud-setup#enabling-apis) for your project and obtained an [API key](https://developers.google.com/maps/documentation/geocoding/get-api-key). You will be asked to provide this API key during installation.
 
-You can read more about this feature [here](https://developers.google.com/maps/documentation/routes/web-service-best-practices#exponential-backoff)
+## Billing
 
+To install an extension, your project must be on the Blaze (pay as you go) plan.
 
-### Additional setup
-Before installing this extension, make sure that you've set up a Cloud Firestore database in your Firebase project.
-A valid Google Maps API key is required as part of the extension installation process.
+You will be charged a small amount (typically around $0.01/month) for the Firebase resources required by this extension (even if it is not used).
 
-#### Billing
-To install an extension, your project must be on the [Blaze (pay as you go) plan](https://firebase.google.com/pricing)
+This extension uses other Firebase and Google Cloud Platform services, which have associated charges if you exceed the service’s no-cost tier:
 
-- You will be charged a small amount (typically around $0.01/month) for the Firebase resources required by this extension (even if it is not used).
-- This extension uses other Firebase and Google Cloud Platform services, which have associated charges if you exceed the service’s no-cost tier:
-  - Cloud Google Maps API
-  - Cloud Firestore
-  - Cloud Functions (Node.js 10+ runtime. [See FAQs](https://firebase.google.com/support/faq#extensions-pricing))
+* [Geocoding API](https://developers.google.com/maps/documentation/geocoding/usage-and-billing)
+* [Distance Matrix API(https://developers.google.com/maps/documentation/distance-matrix/usage-and-billing)
+* Cloud Firestore
+* Cloud Functions (Node.js 14+ runtime. See [FAQs](https://firebase.google.com/support/faq#extensions-pricing))
diff --git a/firestore-geo-functions/extension.yaml b/firestore-geo-functions/extension.yaml
@@ -16,8 +16,8 @@
 # https://firebase.google.com/docs/extensions/alpha/ref-extension-yaml
 
 name: firestore-geo-functions
-version: 0.0.2 
-specVersion: v1beta 
+version: 0.0.2
+specVersion: v1beta
 
 author:
   authorName: Firebase
@@ -27,7 +27,11 @@ displayName: Firestore Geo Functions
 
 description: Provides location based utilities, adding positional infornmation to addresses and calculating distances betweem two locations.
 
-license: Apache-2.0 
+icon: icon.png
+
+tags: [utilities, google-maps, location, logistics]
+
+license: Apache-2.0
 
 sourceUrl: TODO
 
@@ -43,7 +47,6 @@ roles:
   - role: datastore.user
     reason: Allows the extension to read and write to Cloud Firestore.
 
-
 resources:
   - name: updateLatLong
     type: firebaseextensions.v1beta.function

diff --git a/firestore-geo-functions/icon.png b/firestore-geo-functions/icon.png