Merge pull request #353 from square/emmac/add-telemetry-oauth

add userAgentDetail field to oauth sample apps and fix various README…
square · Oct 5, 2022 · b483f19 · b483f19
2 parents 571a5e4 + f4a2c3c
commit b483f19
Show file tree

Hide file tree

Showing 24 changed files with 1,205 additions and 1,013 deletions.
diff --git a/connect-examples/oauth/java/README.md b/connect-examples/oauth/java/README.md
@@ -10,18 +10,19 @@ along with the comments included in `OAuthHandler.java`.
 ## Setup
 
 ### Square Sandbox testing
+
 If you want to run this sample against the Square Sandbox environment:
 
 1. Set your application dashboard to **Sandbox Settings** mode before completing
-the following steps.
+   the following steps.
 1. Add a new **Sandbox Test Account**:
 
    a. Click **New Account** on the dashboard home page.<br>
    b. Give the account a name and pick a country. <br>
    c. Uncheck **Automatically create authorizations for all my current apps**.<br>
 
-1. Click **Launch** on the new test account to open the sandbox seller dashboard
-for the account. The OAuth flow will create an authorization for this account.
+1. Click **Launch** on the new test account to open the sandbox seller dashboard for
+   the account. The OAuth flow will create an authorization for this account.
 
 ### Set your application's Redirect URL
 
@@ -35,20 +36,19 @@ allowed for `localhost` URLs to simplify the development process.
 
 In order for the sample to work, you must specify the following fields in `OAuthHandler.java`:
 
-* Set the value of `ENVIRONMENT` to one of `Environment.SANDBOX`, `Environment.PRODUCTION` or `Environment.CUSTOM`
-
-* For sandbox testing, set the value of `CONNECT_HOST` to `https://connect.squareupsandbox.com`.
-Otherwise, use `https://connect.squareup.com`
+- Set the value of `ENVIRONMENT` to one of `Environment.SANDBOX`, `Environment.PRODUCTION` or `Environment.CUSTOM`
 
-* Replace the value of `APPLICATION_ID` with your application's ID, available on your
-[application dashboard](https://connect.squareup.com/apps).
+- For sandbox testing, set the value of `CONNECT_HOST` to `https://connect.squareupsandbox.com`.
+  Otherwise, use `https://connect.squareup.com`
 
-* Replace the value of `APPLICATION_SECRET` with the application secret, available from the OAuth tab in the Developer Dashboard
+- Replace the value of `APPLICATION_ID` with your application's ID, available on your
+  [application dashboard](https://connect.squareup.com/apps).
 
-* (OPTIONAL) Change the values in the list `SCOPES` to the [permission set](../OAuthPermissions.md) you
-want to authorize the account to get authorization for. If you do not set this value,
-`MERCHANT_PROFILE_READ PAYMENTS_READ SETTLEMENTS_READ BANK_ACCOUNTS_READ` are applied.
+- Replace the value of `APPLICATION_SECRET` with the application secret, available from the OAuth tab in the Developer Dashboard
 
+- (OPTIONAL) Change the values in the list `SCOPES` to the [permission set](../OAuthPermissions.md) you
+  want to authorize the account to get authorization for. If you do not set this value,
+  `MERCHANT_PROFILE_READ PAYMENTS_READ SETTLEMENTS_READ BANK_ACCOUNTS_READ` are applied.
 
 ### Compile with Maven
 
@@ -67,4 +67,5 @@ You can then proceed through the OAuth flow by going to `http://localhost:8000`
 in your web browser.
 
 ## Feedback
-Rate this sample app [here](https://delighted.com/t/Z1xmKSqy)!
+
+Rate this sample app [here](https://delighted.com/t/Z1xmKSqy)!
diff --git a/connect-examples/oauth/java/pom.xml b/connect-examples/oauth/java/pom.xml
@@ -1,24 +1,22 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0"
-    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
   <modelVersion>4.0.0</modelVersion>
 
   <groupId>com.squareup</groupId>
   <artifactId>oauthexample</artifactId>
   <version>1.5-SNAPSHOT</version>
 
-<dependencies>
-  <dependency>
-    <groupId>com.konghq</groupId>
-    <artifactId>unirest-java</artifactId>
-    <version>3.11.09</version>
-  </dependency>
+  <dependencies>
+    <dependency>
+      <groupId>com.konghq</groupId>
+      <artifactId>unirest-java</artifactId>
+      <version>3.11.09</version>
+    </dependency>
 
     <dependency>
       <groupId>com.squareup</groupId>
       <artifactId>square</artifactId>
-      <version>10.0.0.20210421</version>
+      <version>22.0.0.20220720</version>
       <scope>compile</scope>
     </dependency>
   </dependencies>
@@ -48,4 +46,4 @@
     </plugins>
   </build>
 
-</project>
+</project>
diff --git a/connect-examples/oauth/java/src/main/java/com/squareup/oauthexample/OAuthHandler.java b/connect-examples/oauth/java/src/main/java/com/squareup/oauthexample/OAuthHandler.java
@@ -45,21 +45,26 @@ public class OAuthHandler {
   // Options are Environment.SANDBOX, Environment.PRODUCTION
   private static final Environment ENVIRONMENT = Environment.SANDBOX;
 
-  // Your application's ID and secret, available from the OAuth tab in the Developer Dashboard
-  // If you are testing the OAuth flow in the sandbox, use your sandbox application
-  // ID and secret. If you are testing in production, use the production application ID and secret.
-  private static final String APPLICATION_ID =  "REPLACE ME";
-  private static final String APPLICATION_SECRET =  "REPLACE ME";
+  // Your application's ID and secret, available from the OAuth tab in the
+  // Developer Dashboard
+  // If you are testing the OAuth flow in the sandbox, use your sandbox
+  // application
+  // ID and secret. If you are testing in production, use the production
+  // application ID and secret.
+  private static final String APPLICATION_ID = "REPLACE ME";
+  private static final String APPLICATION_SECRET = "REPLACE ME";
   // Modify this list as needed
-  private static final String[] SCOPES = { "MERCHANT_PROFILE_READ", "PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS", "PAYMENTS_WRITE", "PAYMENTS_READ" };
+  private static final String[] SCOPES = { "MERCHANT_PROFILE_READ", "PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS",
+      "PAYMENTS_WRITE", "PAYMENTS_READ" };
   // Serves the authorize link
 
   static class AuthorizeHandler implements HttpHandler {
 
     public void handle(HttpExchange t) throws IOException {
 
       String connect_host;
-      // For testing in sandbox, the base url is "https://connect.squareupsandbox.com",
+      // For testing in sandbox, the base url is
+      // "https://connect.squareupsandbox.com",
       // and https://connect.squareup.com for production mode
       if (ENVIRONMENT == Environment.SANDBOX) {
         connect_host = "https://connect.squareupsandbox.com";
@@ -73,13 +78,12 @@ public void handle(HttpExchange t) throws IOException {
         t.getResponseBody().close();
       }
 
-
       String authorizeURL = String.format(
-        "<a href=\"%s/oauth2/authorize?client_id=%s&scope=%s\">Click here</a> ",
-        connect_host,
-        APPLICATION_ID,
-        String.join("+", SCOPES))
-        + "to authorize the application.";
+          "<a href=\"%s/oauth2/authorize?client_id=%s&scope=%s\">Click here</a> ",
+          connect_host,
+          APPLICATION_ID,
+          String.join("+", SCOPES))
+          + "to authorize the application.";
 
       System.out.println(authorizeURL);
 
@@ -111,7 +115,7 @@ public void handle(HttpExchange t) throws IOException {
       for (NameValuePair param : queryParameters) {
         System.out.println(param.getName());
         System.out.println(param.getValue());
-        if(param.getName().equals("code")) {
+        if (param.getName().equals("code")) {
           authorizationCode = param.getValue();
           break;
         }
@@ -128,8 +132,9 @@ public void handle(HttpExchange t) throws IOException {
       }
 
       SquareClient client = new SquareClient.Builder()
-            .environment(ENVIRONMENT)
-            .build();
+          .environment(ENVIRONMENT)
+          .userAgentDetail("sample_app_oauth_java") // Remove or replace this detail when building your own app
+          .build();
 
       List<String> bodyScopes = new LinkedList<>();
       for (String scope : SCOPES) {
@@ -138,19 +143,19 @@ public void handle(HttpExchange t) throws IOException {
 
       // Create obtain token request body
       ObtainTokenRequest body = new ObtainTokenRequest.Builder(
-        APPLICATION_ID,
-        APPLICATION_SECRET,
-        "authorization_code")
-      .code(authorizationCode)
-      .scopes(bodyScopes)
-      .build();
+          APPLICATION_ID,
+          APPLICATION_SECRET,
+          "authorization_code")
+          .code(authorizationCode)
+          .scopes(bodyScopes)
+          .build();
 
       OAuthApi oAuthApi = client.getOAuthApi();
 
       // Call obtain token API and print the results on success
-      // In production, you should never write tokens to the page. 
-      // You should encrypt the tokens and handle them securely. 
-      oAuthApi.obtainTokenAsync(body).thenAccept(result -> {     
+      // In production, you should never write tokens to the page.
+      // You should encrypt the tokens and handle them securely.
+      oAuthApi.obtainTokenAsync(body).thenAccept(result -> {
         if (result != null) {
           System.out.println("Access token: " + result.getAccessToken());
           System.out.println("Refresh token: " + result.getRefreshToken());

diff --git a/connect-examples/oauth/node/README.md b/connect-examples/oauth/node/README.md
@@ -1,16 +1,12 @@
 # Square OAuth Flow Example (Node.js)
 
-This example demonstrates a bare-bones Node.js implementation of the OAuth flow for
-Square APIs. It serves a link that directs merchants to the OAuth Permissions form
-and handles the result of the authorization, which is sent to your application's
-Redirect URL (specified on the application dashboard).
+This example demonstrates a bare-bones Node.js implementation of the OAuth flow for Square APIs. It serves a link that directs merchants to the OAuth Permissions form and handles the result of the authorization, which is sent to your application's Redirect URL (specified on the application dashboard).
 
 ## Getting started
 
 ### Step 1: Download dependencies
 
-This application requires the Node.js Square SDK and Express, which you install via
-npm. Open your terminal in this directory and type:
+This application requires the Node.js Square SDK and Express, which you install via npm. Open your terminal in this directory and type:
 
 ```
 npm install
@@ -23,17 +19,18 @@ npm install
 1. At the top of the page, set the dashboard mode to the environment that you want to work with by choosing **Sandbox** or **Production**.
 1. Choose **OAuth** in the left navigation pane. The OAuth page is shown.
 1. In the **Redirect URL** box, enter the URL for the callback you will implement to complete the OAuth flow:
-    `http://localhost:8000/callback`
+   `http://localhost:8000/callback`
+
+   You can use HTTP for localhost but an actual web server implementation must use HTTPS.
 
-    You can use HTTP for localhost but an actual web server implementation must use HTTPS.
 1. In the **Application ID** box, copy the application ID.
 1. In the **Application Secret** box, choose **Show**, and then copy the application secret.
 1. Click **Save**.
 1. In your project directory, create a copy of the `.env.example` file and name it `.env`
 1. In the newly created .env file, replace the `your-environment` with either `sandbox` or `production`
 1. Replace the `your-application-id` and `your-application-secret` placeholders with the Sandbox or Production application ID and application secret, respectively.
 
-    Note that OAuth Sandbox credentials begin with a sandbox prefix and that the base URL for calling Sandbox endpoints is https://connect.squareupsandbox.com. When you implement for production, you need production credentials and use https://connect.squareup.com as the base URL.
+   Note that OAuth Sandbox credentials begin with a sandbox prefix and that the base URL for calling Sandbox endpoints is https://connect.squareupsandbox.com. When you implement for production, you need production credentials and use https://connect.squareup.com as the base URL.
 
    **WARNING**: Never check your credentials/access_token into your version control system. We've added `.env` to the `.gitignore` file to help prevent uploading confidential information.
 
@@ -45,15 +42,17 @@ npm install
 
 1. Start the Node server, if it is not running:
 
-    ```
-    npm start
-    ```
+   ```
+   npm start
+   ```
 
 1. Open http://localhost:8000/request_token to start.
 
 # License
+
 Copyright 2020 Square, Inc.
 
+
 ```
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -69,4 +68,5 @@ limitations under the License.
 ```
 
 ## Feedback
-Rate this sample app [here](https://delighted.com/t/Z1xmKSqy)!
+
+Rate this sample app [here](https://delighted.com/t/Z1xmKSqy)!
diff --git a/connect-examples/oauth/node/index.js b/connect-examples/oauth/node/index.js
@@ -65,7 +65,8 @@ const messages = require('./messages');
 
 // Configure Square defcault client
 const squareClient = new Client({
-  environment: environment
+  environment: environment,
+  userAgentDetail: "sample_app_oauth_node" // Remove or replace this detail when building your own app
 });
 
 // Configure Square OAuth API instance