react-native-ankidroid

React Native wrapper for the AnkiDroid API

• AnkiDroid API documentation

Getting started

npm install react-native-ankidroid --save

RN 0.60+

The library will be automatically linked BUT step 4 of the manual installation is still required.

RN < 0.60

Mostly automatic installation

react-native link react-native-ankidroid

• Step 4 of the manual installation is still required.

Manual installation

Android

1. Open up android/app/src/main/java/[...]/MainActivity.java

• Add import com.is343.reactnativeankidroid.AnkiDroidPackage; to the imports at the top of the file
• Add new AnkiDroidPackage() to the list returned by the getPackages() method

2. Append the following lines to android/settings.gradle:

   include ':react-native-ankidroid'
   project(':react-native-ankidroid').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-ankidroid/android')

3. Insert the following lines inside the dependencies block in android/app/build.gradle:

     implementation project(':react-native-ankidroid')

4. Add the following lines to /android/app/src/main/res/AndroidManifest.xml:

   <manifest xmlns:android="http://schemas.android.com/apk/res/android"
       xmlns:tools="http://schemas.android.com/tools" // <---- ADD HERE
       package="com.yourpackage.name">
   
       <uses-permission android:name="android.permission.INTERNET" />
       <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW"/>
   
       <application
         android:name="com.yourpackage.name.MainApplication"
         android:label="@string/app_name"
         android:icon="@mipmap/ic_launcher"
         android:allowBackup="true"
         android:theme="@style/AppTheme"
         tools:replace="android:allowBackup" // <---- ADD HERE
         >

• This will prevent the following error by forcing the compiler to use your app's attribute:

    Execution failed for task ':app:processDebugManifest'.
    > Manifest merger failed : Attribute application@allowBackup value=(false) from AndroidManifest.xml:15:7-34 is also present at [com.github.ankidroid:Anki-Android:api-v1.1.0] AndroidManife
    st.xml:14:9-35 value=(true).
    Suggestion: add 'tools:replace="android:allowBackup"' to <application> element at AndroidManifest.xml:7:5-117 to override.

Usage

import AnkiDroid from 'react-native-ankidroid';

await AnkiDroid.isApiAvailable();

Static Methods

AnkiDroid.____________ *(returns a Promise)

• isApiAvailable()* - checks if the AnkiDroid API is avaiable (AnkiDroid is installed on the device) in order to access the API, AnkiDroid may need to be installed before the react native app
• checkPermission()*
• requestPermission(rationale)* -- rationale (optional)
• getSelectedDeckName()* -- gets the name of the currently selected deck -- returns a response tuple
• getDeckList()* -- gets a list of the names and IDs of each deck -- returns a response tuple
• getModelList()* -- gets a list of the names and IDs of each model -- returns a response tuple
• getFieldList(modelName, modelId)* -- gets a list of all field names for a specific model -- only one of modelName or modelId is required -- returns a response tuple
• uploadMediaFromUri(fileUri, preferredName, mimeType)* -- gets a list of all field names for a specific model -- fileUri: the location of the media to upload -- preferredName: the name that will be used to access the media in the card -- mimeType: can be either "audio" or "image" -- returns a response tuple -- import media into notes with <img src="myimage.jpg"> and [sound:myaudio.mp3] -- official anki docs can be found here -- Both AnkiDroid and your app require the android.permission.MANAGE_EXTERNAL_STORAGE permission granted if you intend to upload a file from external storage

Creating a class instance

• new AnkiDroid(setupOptions) - creates an instance of your deck

The Response tuple

• some methods will return a tuple in the form of [error, responseData] -- when there is no error the first value in the tuple will be null. The data we want to retrieve will always be in the second value

setupOptions object

| Params | Type | Required | Description | | --------------- | :--------------: | ------------------------------------ | ---------------------------------------------------------- | | deckProperties | object | optional if deckId exists | properties required to search by name / create a new deck | | deckId | string | number | optional if deckProperties exists | Id of the existing deck to add notes to | | modelProperties | object | optional if modelId exists | Id of the existing model to add notes to | | modelId | string | number | optional if modelProperties exists | properties required to search by name / create a new model |

deckProperties object

| Params | Type | Default | Description | | --------- | :----: | -------- | -------------------------------------------------------------------------------------------------- | | reference | string | REQUIRED | Deck reference name to store locally in SharedPreferences | | name | string | REQUIRED | Name of the deck to create / add notes to (Will first search for deck by name before creating) |

modelProperties object

| Params | Type | Default | Description | | -------------- | :------: | -------- | ------------------------------------------------------------------------------------------------------------------------- | | name | string | REQUIRED | Name of the model used / created for notes (Will first search for deck by name before creating) | | reference | string | REQUIRED | Model reference name to store locally in SharedPreferences | | modelFields | string[] | REQUIRED | The names of the fields used for the note's model during creation / use (modelFields.length === valueFields.length) | | cardNames | string[] | REQUIRED | Names for the front/back sides of the model (cardNames.length === 2) | | questionFormat | string[] | REQUIRED | Question formatting for each direction of (questionFormat.length === 2) variable names MUST match modelFields names | | answerFormat | string[] | REQUIRED | Answer formatting for each direction of (answerFormat.length === 2) variable names MUST match modelFields names | | tags | string[] | null | Tags to attach to added notes | | css | string | null | css styling information to be shared across all cards. (null for default CSS) |

AnkiDroid Class Instances

• addNote(valueFields, modelFields)

  | Param | Type | Description | | ----------- | :------: | --------------------------------------------------------------------------------------------------------------- | | valueFields | string[] | The values for the corresponding model fields. (valueFields.length === modelFields.length) | | modelFields | string[] | The model fields that correspond to the model that will be used. (values must exactly match the model used) |

Gotchas

• Once a model or reference has been created with a certain name, the format must match for all subsequent cards you wish to create using said model
• If you intend to change the format in any way, you must use new names as a reference

Example

///////////////////////////////////
// SETTING UP THE DECK AND MODEL //
///////////////////////////////////

// Name of deck which will be created in AnkiDroid
const deckName = 'API Sample Name';
// Name of model which will be created in AnkiDroid (can be any string)
const modelName = 'Sample Model Name';
// Used to save a reference to this deck in the SharedPreferences (can be any string)
const dbDeckReference = 'com.your.app.decks';
// Used to save a reference to this model in the SharedPreferences (can be any string)
const dbModelReference = 'com.your.app.models';
// Optional space separated list of tags to add to every note
const tags = ['API_Sample', 'my', 'tags'];
// List of field names that will be used in AnkiDroid model
const modelFields = [
  'Word',
  'Translation',
  'Meaning',
  'Grammar',
  'Idiom',
  'IdiomTranslation',
  'IdiomMeaning',
];
// List of card names that will be used in AnkiDroid (one for each direction of learning)
const cardNames = ['Korean>English', 'English>Korean'];
// CSS to share between all the cards (optional).
const css = `.card {
  font-family: NotoSansKR;
  font-size: 24px;
  text-align: center;
  color: black;
  background-color: white;
  word-wrap: break-word;
}
.big { font-size: 48px; }
.small { font-size: 18px;}`;
// Template for the question of each card
const questionFmt1 = '<div class=big>{{Word}}</div><br>{{Grammar}}';
const questionFmt2 =
  '{{Meaning}}<br><br><div class=small>{{Grammar}}<br><br>({{Idiom}})</div>';
const questionFormat = [questionFmt1, questionFmt2];
// Template for the answer (this example is identical for both sides)
const answerFmt1 = `<div class=big>{{Translation}}</div><br>{{Meaning}}
<br><br>
{{IdiomTranslation}}<br>
<a href=\"#\" onclick=\"document.getElementById('hint').style.display='block';return false;\">Idiom Meaning</a>
<div id="hint" style="display: none">{{IdiomMeaning}}</div>
<br><br>
{{Grammar}}<br><div class=small>{{Tags}}</div>`;
const answerFormat = [answerFmt1, answerFmt1];

//////////////////
// ADDING NOTES //
//////////////////

const deckProperties = {
  name: deckName,
  reference: dbDeckReference,
};
const modelProperties = {
  name: modelName,
  reference: dbModelReference,
  fields: modelFields,
  tags,
  cardNames,
  questionFormat,
  answerFormat,
  css,
};

const valueFields = [
  '사랑',
  'love',
  'The attitude of sincerely caring about someone out of affection.',
  'noun',
  '사랑을 속삭이다',
  'whisper love',
  'For lovers to have a conversation of love.',
];

const settings = {
  modelId: undefined,
  modelProperties: modelProperties,
  deckId: undefined,
  deckProperties: deckProperties,
};

const myAnkiDeck = new AnkiDroid(settings);

myAnkiDeck.addNote(valueFields, modelFields);
// returns a promise that returns the added note ID

const newNote = [
  '여행사',
  'travel agency',
  'A company that offers an array of services for travel, including transportation, accomodaton, tour guide, etc.',
  'noun',
  '',
  '',
  '',
];

myAnkiDeck.addNote(newNote, modelFields);

Demo App

• A demo app is in the example folder. Just cd into the demo app directory and npm install && npm run android

Card setup / References

• Anki Cards and Templates Documentation
• AnkiDroid API sample app - this was referenced extensively while making this

Todo

• [ ] add basic card
• [ ] AnkiDroid intent API
• [ ] add multiple notes at once
• [x] ~~upload media~~
• [x] ~~add to default deck~~
• [x] ~~create by model ID / deck ID~~
• [x] ~~get selected deck~~
• [x] ~~get model field values~~
• [x] ~~get model list~~
• [x] ~~get deck list~~
• [x] ~~detailed examples~~
• [x] ~~typescript~~

Contributions

Pull requests welcome!