apiVersioning and developerContact implementation for AnkiDroid functions call from WebView

AnkiDroid/build.gradle

@@ -266,4 +266,7 @@ dependencies {
     androidTestImplementation 'androidx.test.ext:junit:1.1.1'
     androidTestImplementation 'androidx.test:rules:1.2.0'
     androidTestImplementation 'org.smali:dexlib2:2.4.0'
+
+    //For AnkiDroid JS API Versioning
+    implementation "com.github.zafarkhaja:java-semver:0.9.0"
 }

AnkiDroid/src/main/java/com/ichi2/anki/AbstractFlashcardViewer.java

@@ -42,6 +42,7 @@
 
 import androidx.annotation.CheckResult;
 import androidx.annotation.IdRes;
+import androidx.annotation.IntDef;
 import androidx.annotation.NonNull;
 import androidx.annotation.Nullable;
 import androidx.annotation.VisibleForTesting;
@@ -84,6 +85,8 @@
 
 import com.afollestad.materialdialogs.MaterialDialog;
 import com.afollestad.materialdialogs.util.TypefaceHelper;
+import com.google.android.material.snackbar.Snackbar;
+import com.google.gson.Gson;
 import com.ichi2.anim.ActivityTransitionAnimation;
 import com.ichi2.anim.ViewAnimation;
 import com.ichi2.anki.dialogs.TagsDialog;
@@ -123,9 +126,12 @@
 import java.io.FileOutputStream;
 import java.io.IOException;
 import java.io.UnsupportedEncodingException;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
 import java.lang.ref.WeakReference;
 import java.net.URLDecoder;
 import java.util.ArrayList;
+import java.util.HashMap;
 import java.util.HashSet;
 import java.util.LinkedHashSet;
 import java.util.Set;
@@ -142,6 +148,8 @@
 import static com.ichi2.anki.reviewer.CardMarker.*;
 import static com.ichi2.async.CollectionTask.TASK_TYPE.*;
 
+import com.github.zafarkhaja.semver.Version;
+
 @SuppressWarnings({"PMD.AvoidThrowingRawExceptionTypes","PMD.FieldDeclarationsShouldBeAtStartOfClass"})
 public abstract class AbstractFlashcardViewer extends NavigationDrawerActivity implements ReviewerUi, CommandProcessor {
 
@@ -189,6 +197,20 @@ public abstract class AbstractFlashcardViewer extends NavigationDrawerActivity i
 
     // ETA
     private int eta;
+    // JavaScript Versioning
+    protected String mCardSuppliedApiVersion = "";
+    protected String mCardSuppliedDeveloperContact  = "";
+
+    private static final String sCurrentJsApiVersion = "0.0.1";
+    private static final String sMinimumJsApiVersion = "0.0.1";
+
+    // JS API ERROR CODE
+    private static final int ankiJsErrorCodeDefault = 0;
+    private static final int ankiJsErrorCodeMarkCard = 1;
+    private static final int ankiJsErrorCodeFlagCard = 2;
+
+    // JS api list enable/disable status
+    private HashMap<String, Boolean> mJsApiListMap = new HashMap<String, Boolean>();
 
     private boolean isInFullscreen;
 
@@ -3189,11 +3211,28 @@ private boolean filterUrl(String url) {
             }
             // mark card using javascript
             if (url.startsWith("signal:mark_current_card")) {
-                executeCommand(COMMAND_MARK);
+                if (isAnkiApiNull("markCard")) {
+                    showDeveloperContact(ankiJsErrorCodeDefault);
+                    return true;
+                } else if (mJsApiListMap.get("markCard")) {
+                    executeCommand(COMMAND_MARK);
+                } else {
+                    // see 02-string.xml
+                    showDeveloperContact(ankiJsErrorCodeMarkCard);
+                }
                 return true;
             }
             // flag card (blue, green, orange, red) using javascript from AnkiDroid webview
             if (url.startsWith("signal:flag_")) {
+                if (isAnkiApiNull("toggleFlag")) {
+                    showDeveloperContact(ankiJsErrorCodeDefault);
+                    return true;
+                } else if (!mJsApiListMap.get("toggleFlag")) {
+                    // see 02-string.xml
+                    showDeveloperContact(ankiJsErrorCodeFlagCard);
+                    return true;
+                }
+
                 String mFlag = url.replaceFirst("signal:flag_","");
                 switch (mFlag) {
                     case "none": executeCommand(COMMAND_UNSET_FLAG);
@@ -3450,6 +3489,81 @@ void handleUrlFromJavascript(String url) {
         }
     }
 
+    // Check if value null
+    private boolean isAnkiApiNull(String api) {
+        if (mJsApiListMap.get(api) == null) {
+            return true;
+        }
+        return false;
+    }
+
+    /*
+     * see 02-strings.xml
+     * Show Error code when mark card or flag card unsupported
+     * 1 - mark card
+     * 2 - flag card
+     *
+     * show developer contact if js api used in card is deprecated
+     */
+    private void showDeveloperContact(int errorCode) {
+        String errorMsg = getString(R.string.anki_js_error_code, errorCode);
+
+        View parentLayout = findViewById(android.R.id.content);
+        String snackbarMsg;
+        snackbarMsg = getString(R.string.api_version_developer_contact, mCardSuppliedDeveloperContact, errorMsg);
+
+        Snackbar snackbar = Snackbar.make(parentLayout, snackbarMsg, Snackbar.LENGTH_LONG);
+        View snackbarView = snackbar.getView();
+        TextView snackTextView = snackbarView.findViewById(com.google.android.material.R.id.snackbar_text);
+        snackTextView.setTextColor(Color.WHITE);
+        snackTextView.setMaxLines(3);
+
+        snackbar.setActionTextColor(Color.MAGENTA)
+                .setAction(getString(R.string.reviewer_invalid_api_version_visit_documentation), view -> {
+                    openUrl(Uri.parse("https://github.com/ankidroid/Anki-Android/wiki"));
+                });
+
+        snackbar.show();
+    }
+
+    /**
+     * Supplied api version must be equal to current api version to call mark card, toggle flag functions etc.
+     */
+    private boolean requireApiVersion(String apiVer, String apiDevContact) {
+        try {
+
+            if (TextUtils.isEmpty(apiDevContact)) {
+                return false;
+            }
+
+            Version mVersionCurrent = Version.valueOf(sCurrentJsApiVersion);
+            Version mVersionSupplied = Version.valueOf(apiVer);
+
+            /*
+            * if api major version equals to supplied major version then return true and also check for minor version and patch version
+            * show toast for update and contact developer if need updates
+            * otherwise return false
+            */
+            if (mVersionSupplied.equals(mVersionCurrent)) {
+                return true;
+            } else if (mVersionSupplied.lessThan(mVersionCurrent)) {
+                UIUtils.showThemedToast(AbstractFlashcardViewer.this, getString(R.string.update_js_api_version, mCardSuppliedDeveloperContact), false);
+
+                if (mVersionSupplied.greaterThanOrEqualTo(Version.valueOf(sMinimumJsApiVersion))) {
+                    return true;
+                } else {
+                    return false;
+                }
+            } else {
+                UIUtils.showThemedToast(AbstractFlashcardViewer.this, getString(R.string.valid_js_api_version, mCardSuppliedDeveloperContact), false);
+                return false;
+            }
+        } catch (Exception e) {
+          Timber.i(e, "requireApiVersion::exception");
+        }
+        return false;
+    }
+
     @VisibleForTesting
     void loadInitialCard() {
         CollectionTask.launchCollectionTask(ANSWER_CARD, mAnswerCardHandler(false),
@@ -3498,6 +3612,49 @@ protected void showTagsDialog() {
  */
     public class JavaScriptFunction {
 
+        private final Gson sGson = new Gson();
+        // list of api that can be accessed
+        private final String[] sApiList = {"toggleFlag", "markCard"};
+
+        // api disabled when valid api version not provided
+        private void disableJsApi() {
+            for (int i = 0; i < sApiList.length; i++) {
+                mJsApiListMap.put(sApiList[i], false);
+            }
+        }
+
+        // if supplied api version match then enable api
+        private void enableJsApi() {
+            for (int i = 0; i < sApiList.length; i++) {
+                mJsApiListMap.put(sApiList[i], true);
+            }
+        }
+
+        @JavascriptInterface
+        public String init(String jsonData) {
+            JSONObject data;
+            String apiStatusJson = "";
+
+            try {
+                data = new JSONObject(jsonData);
+                if (!(data == JSONObject.NULL)) {
+                    mCardSuppliedApiVersion = data.optString("version", "");
+                    mCardSuppliedDeveloperContact  = data.optString("developer", "");
+
+                    if (requireApiVersion(mCardSuppliedApiVersion, mCardSuppliedDeveloperContact)) {
+                        enableJsApi();
+                    } else {
+                        disableJsApi();
+                    }
+                    apiStatusJson = sGson.toJson(mJsApiListMap);
+                }
+
+            } catch (JSONException j) {
+                UIUtils.showThemedToast(AbstractFlashcardViewer.this, getString(R.string.invalid_json_data, j.getLocalizedMessage()), false);
+            }
+            return String.valueOf(apiStatusJson);
+        }
+
         @JavascriptInterface
         public String ankiGetNewCardCount() {
             return newCount.toString();

AnkiDroid/src/main/res/values/02-strings.xml

@@ -279,4 +279,16 @@
     <string name="white_board_image_saved">Whiteboard image saved to %s</string>
 
     <string name="title_whiteboard_pen_color">Whiteboard pen color</string>
+
+    <string name="api_version_developer_contact">This card uses unsupported AnkiDroid features. Contact developer %s, or view the wiki. %s</string>
+    <string name="invalid_json_data">Card provided invalid data. %s</string>
+    <string name="valid_js_api_version">Invalid AnkiDroid JS API version. Contact developer %s, or view wiki</string>
+    <string name="update_js_api_version">AnkiDroid JS API update available. Contact developer %s, or view wiki</string>
+    <string name="reviewer_invalid_api_version_visit_documentation">View</string>
+    <string name="update_js_api_patch_version">AnkiDroid JS API patch update available. Contact developer %s, or view wiki.</string>
+    <string name="update_js_api_minor_version">AnkiDroid JS API minor update available. Contact developer %s, or view wiki.</string>
+    <string name="js_api_not_implemented">JS API not implemented to current deck. View wiki.</string>
+
+    <!-- Error codes for AnkiDroid JS API-->
+    <string name="anki_js_error_code">(Error Code:%d)</string>
 </resources>